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. The config 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 signed

  • newsfeed: For good news, for warnings, or to display site-specific data

  • value: For displaying values that grow or shrink with time

  • chart: TBD

  • media: 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.

200: OK

{
    // Response
}

304: Not Modified If-None-Match header matches ETag

{
    // Response
}

500: Internal Server Error

{
    // Response
}

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

Name	Type	Description
lang	string	Request all translatable (human-readable) config and module content in language lang. Valid: en: English (default) pt: Portuguese Any ISO 639-1 2-letter language code may be requested for forward compatibility. Data will fall back to en. Many more languages coming soon!
device	string	Most clocks can use generic but clock builders should choose a unique string here. Check its existence by requesting the URL and examining the value returned in data.config.device – if your device string is available, the text returned will say generic.

200 The object returned will contain status: "success". Configuration and Module information will be returned within the data object in the "config": {...} and "modules": {...} objects respectively. An ISO-8601 timestamp and full API version string are also included.

{
  "data": {
    "config": {
      "device": "generic",
      ...
    },
    "modules": {
      ...
    },
    "api_version": "v2"
  },
  "status": "success"
}

500 Errors return an object containing status: "error".

{
  "message": "ClimateClock API has encountered an error",
  "status": "error"
}

304: Not Modified If-None-Match header matches ETag

{
    // Response
}

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:

{
  "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

Module Specification

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:

Essential data

{
  "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: 👉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_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 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.

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

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.

Module type: 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:

{
  "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.

Module type: value

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 $≤1$ 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.

Linear

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: $f(t_{seconds}) = initial + rate * t_{seconds}$

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

⚠️ 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 $f(t_{seconds}) = \infty$

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:

JavaScript

// TODO: JavaScript example

Python

# TODO: Python example