Climate Clock API
The v2 Climate Clock API is intended to provide a unified data source to be used by a variety of Climate Clock implementations. It is intended to be simple to use in most cases, with more complex features available optionally for specific devices as needed.
For convenience, everything necessary to implement a Climate Clock can be retrieved from a single endpoint which may be polled as needed. The
/v2/clock.jsonand related endpoints provide two primary objects whose purpose should be understood when implementing Climate Clocks:
configDevice-specific clock configuration data Configuration data is meant to provide implementation details which pertain to things like presentation and branding. Using data from this source ensures that clocks maintain presentation consistent with the goals of the Climate Clock project. This is a source of useful defaults, particularly of interest when implementing certain classes of clock devices, such as Portable Action Clocks, whose owners likely have no interest in configuring or maintaining the devices. The
configobject also specifies a list of modules which are presently being highlighted by the project for display by clocks.
modulesModular specifications of clock data for display Climate Clocks serve different purposes depending on where they're installed, the size of their screens, or who owns and maintains them. To solve the needs of different clocks, we categorize each thing to be displayed on a clock as a "module." A module can be the countdown until 1.5°C global temperature rise is locked in as predicted by the IPCC, or it can be series of headlines for a news ticker, or another kind of metric. Modules come in different types:
timer: For countdowns, or elapsed time such as days since Paris Climate Accords were signed
newsfeed: For good news, for warnings, or to display site-specific data
value: For displaying values that grow or shrink with time
Generic data in English
Multilingual data with support for your custom device
See the section titled Module Specification for information about how frequently to poll this endpoint.
Configuration data is provided within the
data.configobject of JSON returned by v2 endpoints like so:
The most basic configuration information provided within
configfor all device types, is a list of available languages, and a list of suggested modules for display:
"langs": ["en", "pt"],
TODO: Document full configuration & branding spec
Modules are provided as named objects within the
data.modulesobject of JSON returned by v2 endpoints like so:
Each module contains the following:
"type": "chart" | "media" | "newsfeed" | "timer" | "value",
"flavor": "lifeline" | "deadline" | "neutral",
"description": "A human-readable description of this module's purpose",
type: Specifies which module implementation can display this module.
Whether this module should follow the Lifeline, Deadline or Neutral display specification.
description: A full description of what this module represents.
update_interval_seconds: This module's data will be updated no more frequently than the given number of seconds. This tells clients how long to wait before polling the endpoint with the intention to find new information for this module.
Clients should adjust their API polling to match the smallest value of
update_interval_secondsamong the modules they intend to display. To comply with intended clock behavior, use the most recent values of
update_interval_secondsyour client has received. This allows modules with long polling intervals to indicate they should now be polled more frequently, and vice-versa.
"A Human-readable Label",
"A Shorter Label",
labels: a list of 1 or more text labels, presented in longest to shortest, for display where possible alongside module data. Opt to display the longest possible label within the space of your clock display.
lang: An ISO 639-1 language code. If the module has responded to your request for content in another language (e.g. your request to
langwill indicate the language of content you received. It's currently possible to ask for content in any language, but as of this writing only English content is available. This allows module implementations to act based on the availability of translated content.
Modules also contain data pertinent to their
Fully-compliant Climate Clocks should implement displays for all module types, allowing API data to dynamically determine which modules to display based on the
Modules of type
timerare meant to express a countdown to a deadline, or time elapsed. A timer contains a timestamp in the past or future.
timestamp: Implementations should display a clock showing time until or since the ISO 8601 timestamp given. The ISO 8601 timestamp will include a time zone offset, but implementations unable to make use of timezone data (like small embedded clocks) can safely assume the use of UTC, as all timestamps are provided in UTC.
Modules of type
newsfeedare intended to display a series of text items for the implementation of a news ticker-like display. Each module of this type provides an array of objects representing headlines within the news feed:
"headline": "No stability in sight!",
"headline_original": "Climate stabilization not likely before 2032 warn scientists",
"source": "Example News",
"summary": "Optional summary of this piece of news..."
"headline": "Example News says More News!",
newsfeed: An array of newsfeed items in reverse chronological order, each containing:
date: An ISO 8601 date or timestamp indicating the approximate publication date of this news item.
headline: A newsfeed headline. (optional)
headline_original: The headline as originally published—the
headlinefield may be editorialized by the project.
source: Source of this news (a publication name).
link: Link to the article or source of this news.
summary: A write up describing the significance of this news.
Modules of type
valuerepresent a value which grows or shrinks over time. All value modules contain:
"growth": "linear" | "exponential",
"Tons of CO₂ Emitted",
initial: The growth equation's starting value.
timestamp: An ISO 8601 timestamp for the starting value.
growth: The type of growth represented.
resolution: A number
indicating the smallest value to be displayed (e.g. 0.001 implying no more than 3 decimal digits should be shown). This is related to the concept of significant figures, but simpler. (optional)
unit_labels: A list of 1 or more text unit labels for this value, presented longest to shortest, for display where possible alongside value data. Opt to display the longest possible unit label within the space of your clock display.
Modules of type
module.growth == "linear"represent linear growth and contain:
rate: Rate of change per second.
Linear growth can be calculated as:
Be aware that
ratevalues may be extremely large or small. Take care in your implementation to preserve the precision provided. See: https://en.wikipedia.org/wiki/Floating-point_arithmetic#Minimizing_the_effect_of_accuracy_problems
Do not use. Data model for non-linear growth values is TBD as of 2021-02-17
Modules of type
module.growth == "exponential"represent exponential growth and contain:
Exponential growth can be calculated as
Here, a simple client connects to the API and implements the well-known
carbon_deadline_1representing our time to act before we lock in 1.5°C global temperature rise:
# TODO: Python example