Climate Clock API
Overview
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.
Simple JSON endpoints
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
Generic data in English
GET
https://api.climateclock.world/v2/clock.json
Fetch all available Climate Clock modules in English, and one generic configuration object. This endpoint should always return JSON.
Multilingual data with support for your custom device
GET
https://api.climateclock.world/v2{/device}/clock{.lang}.json
Fetch all available Climate Clock modules in the requested language, and one relevant configuration object for your device.
Need to customize the data we provide? Don't like the text we provide? What about next year? Future-proof your clock by providing a unique device string for your custom clock.
This endpoint should always return JSON.
Path Parameters
See the section titled Module Specification for information about how frequently to poll this endpoint.
Config Specification
Configuration data is provided within the data.config
object of JSON returned by v2 endpoints like so:
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:
Module Specification
Modules are provided as named objects within the data.modules
object of JSON returned by v2 endpoints like so:
Each module contains the following:
Essential data
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.
Optional data
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.
Module-specific data
Modules also contain data pertinent to their type
.
Module types
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.
Module type: timer
timer
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.
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.
Module type: newsfeed
newsfeed
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:
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.
Module type: value
value
Modules of type value
represent a value which grows or shrinks over time. All value modules contain:
Linear
Modules of type value
with module.growth == "linear"
represent linear growth and contain:
rate
: Rate of change per second.
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
Exponential
Modules of type value
with module.growth == "exponential"
represent exponential growth and contain:
Example
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:
Last updated