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.json
and related endpoints provide two primary objects whose purpose should be understood when implementing Climate Clocks:config
Device-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. Theconfig
object also specifies a list of modules which are presently being highlighted by the project for display by clocks.modules
Modular 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 signednewsfeed
: For good news, for warnings, or to display site-specific datavalue
: For displaying values that grow or shrink with timechart
: TBDmedia
: TBD
get
https://api.climateclock.world
/v2/clock.json
Generic data in English
get
https://api.climateclock.world
/v2{/device}/clock{.lang}.json
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.config
object of JSON returned by v2 endpoints like so:{
"data": {
"config": {
...
},
...
The most basic configuration information provided within
config
for all device types, is a list of available languages, and a list of suggested modules for display:{
"device": "generic",
"langs": ["en", "pt"],
"modules": [
"carbon_deadline_1",
"renewables_1",
"newsfeed_1"
],
...
}
TODO: Document full configuration & branding spec
⚠
Modules are provided as named objects within the
data.modules
object of JSON returned by v2 endpoints like so:{
"data": {
"modules": {
"module_1": {
...
},
"module_2": {
...
},
...
},
...
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",
"update_interval_seconds": 86400,
...
type
: Specifies which module implementation can display this module.
flavor
: 👉
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_seconds
among the modules they intend to display.
To comply with intended clock behavior, use the most recent values of update_interval_seconds
your client has received. This allows modules with long polling intervals to indicate they should now be polled more frequently, and vice-versa. ...
"labels": [
"A Human-readable Label",
"A Shorter Label",
"Short Lbl",
"Lbl",
],
"lang": "en"
...
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 /v2/reloj_madrid/clock.es.json
), lang
will 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
type
.Fully-compliant Climate Clocks should implement displays for all module types, allowing API data to dynamically determine which modules to display based on the
config.modules
list.Modules of type
timer
are meant to express a countdown to a deadline, or time elapsed. A timer contains a timestamp in the past or future.{
"type": "timer",
...
"timestamp": "2032-01-01T00:00:00+00:00"
}
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
newsfeed
are 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:{
"type": "newsfeed",
...
"newsfeed": [
{
"date": "2021-01-01T00:00:00+00:00",
"headline": "No stability in sight!",
"headline_original": "Climate stabilization not likely before 2032 warn scientists",
"source": "Example News",
"link": "https://example.com/climate-stability",
"summary": "Optional summary of this piece of news..."
},
{
"date": "2021-01-01T00:00:00+00:00",
"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 headline
field 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
value
represent a value which grows or shrinks over time. All value modules contain:{
"type": "value",
...
"initial": 9.99,
"timestamp": "2018-01-01T00:00:00+00:00",
"growth": "linear" | "exponential",
"resolution": 0.01,
"unit_labels": [
"Tons of CO₂ Emitted",
"Tons CO₂",
"T.CO₂"
]
}
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
value
with module.growth == "linear"
represent linear growth and contain:{
"growth": "linear",
...
"rate": 2.8368383376368776e-08,
}
rate
: Rate of change per second. Linear growth can be calculated as:
Be aware that
rate
values 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
value
with module.growth == "exponential"
represent exponential growth and contain:{
"growth": "exponential",
...
}
Exponential growth can be calculated as
Here, a simple client connects to the API and implements the well-known
timer
module named carbon_deadline_1
representing our time to act before we lock in 1.5°C global temperature rise:JavaScript
Python
// TODO: JavaScript example
# TODO: Python example
Last modified 7mo ago