/v1/clockendpoint provides 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
data.configobject of JSON returned by
configfor all device types is a list of suggested modules for display:
data.modulesobject of JSON returned by
type: Specifies which module implementation can display this module.
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.
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 by query-string such as
?lang=es), 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.
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.
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:
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.
valuerepresent a value which grows or shrinks over time. All value modules contain:
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
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.
module.growth == "linear"represent linear growth and contain:
rate: Rate of change per second.
module.growth == "exponential"represent exponential growth and contain:
carbon_deadline_1representing our time to act before we lock in 1.5°C global temperature rise: