Introduction

The climatic API is designed to help developers build tools that focus on carbon footprint automation for a broad range of activities.

This API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All requests must be made over HTTPS. Calls made over plain HTTP will fail.

Base URL

https://api.climatiq.io

Methods

All endpoints support GET and POST methods. They share the same parameters, but serve different use cases.

GET

Volatile Estimations

GET requests have low reponse times and latency. Designed for non-persistent emission calculations.
POST

Estimate Tracking

POST requests are persisted and used for Analytics. Designed for accounting or emission tracking.

Responses

All responses return a unified JSON format, providing a detailed amount of greenhouse gas emissions (CO2, N20, CH4 and CO2E):

{
"co2e": "number",
"co2": "number",
"n2o": "number",
"ch4": "number",
"unit": "string"
}

CO2e

Typically, greenhouse gas emissions are reported in units of carbon dioxide equivalent (CO2e). Gases are converted to CO2e by multiplying by their global warming potential (GWP).

Source: Intergovernmental Panel on Climate Change (IPCC), Fourth Assessment

Errors

The climatiq API uses conventional HTTP response codes to indicate the success or failure of an API request.

Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (not enough required parameters haven been provided, or their values are not supported, etc). Codes in the 5xx range indicate an error with the API servers. We put a lot of effort on stability, and server errors are very rare. If they ever appear, they will be automatically reported to our team, to be fixed as soon as possible.

Status Codes

200 OK

Everything worked as expected.

400 Bad Request

The request was unacceptable, often due to missing a required parameter.

401 Unauthorized

No valid API key provided.

402 Request Failed

The parameters were valid but the request failed.

403 Forbidden

The API key doesn't have permissions to perform the request.

404 Not Found

The requested resource doesn't exist.

500, 502, 503, 504 Server Errors

Something went wrong on our servers.

Authentication

We use API keys in form of bearer token to authenticate requests. Always provide the Authorization header containing your API KEY as bearer token:

Authorization: Bearer <API_KEY>

You can get and manage your API keys in your Project Settings.

Note: Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and store them encrypten when possible.

Versioning

API stability is always prioritised, but when backwards compatibility is not possible, we will issue a new version of the API.

API Versions can be defined using the Climatiq-Version header. If no version is defined, the latest version will be used.

Climatiq-Version: 1

If low maintenance is important for your application, we sugget you always define a version header, to make sure no breaking changes will affect.

Estimate API

The Estimation API is designed to provide emission factors to estimate greenhouse emissions of a particular activity.

Electricity

Used to calculate emissions generated by power consumption

Parameters

  • energy number

    Amount of energy consumed in kwh

    Required
  • region string

    Define a region to increase accuracy. Defaults to eu

    Values:eueu-deeu-frsee all

curl "https://api.climatiq.io/estimate/electricity?energy=50&country=de" \
-H "Authorization: Bearer AUTH_TOKEN"
-H "Content-Type: application/json"

Vehicle

Used to calculate emissions of a vehicle by distance

Parameters

  • category string

    Vehicle category

    Required

    Values:carlightheavymotorbike

  • distance number

    Total distance in km

    Required
  • fuel string

    Type of fuel used. Defaults to "petrol"

    Values:petroldieselLPGE5E10E85

  • region string

    Define a region to increase accuracy. Defaults to eu

    Values:eueu-deeu-frsee all

curl "https://api.climatiq.io/estimate/vehicle?category=light&distance=20&fuel=diesel" \
-H "Authorization: Bearer AUTH_TOKEN"
-H "Content-Type: application/json"

Fuel

Fuel combustion emission factors are based on Tier 1 methods, provided by the European Environment Agency (EEA) and the Greenhouse Gas Protocol (GHGProtocol)

Parameters

  • type string

    Type of fuel used

    Required

    Values:petroldieselLPGE5E10E85

  • amount number

    Amount of fuel consumed in `liters`

    Required
  • region string

    Define a region to increase accuracy. Defaults to eu

    Values:eueu-deeu-frsee all

curl "https://api.climatiq.io/estimate/fuel?type=diesel&amount=10&region=eu" \
-H "Authorization: Bearer AUTH_TOKEN"
-H "Content-Type: application/json"

Flight

Used to calculate emissions of a flight

Parameters

  • airports string[]

    A comma separated list of airpots describing the route

    Required
  • class string

    Cabin class. Defaults to "economy"

    Values:economypremium

curl "https://api.climatiq.io/estimate/flight?airports=ber,pmi&class=premium" \
-H "Authorization: Bearer AUTH_TOKEN"
-H "Content-Type: application/json"

Shipping

Used to calculate emissions generated by shipping goods

Parameters

  • weight number

    Total weight in `kg`

    Required
  • distance number

    Distance in `km`

    Required
  • method string

    Shipping method

    Required

    Values:shiptraintruckplane

curl "https://api.climatiq.io/estimate/shipping?weight=20&distance=20&method=plane" \
-H "Authorization: Bearer AUTH_TOKEN"
-H "Content-Type: application/json"