API Reference

Introduction

Climatiq helps you capture the environmental footprint created by a broad range of business activities.

We simplify the process of collecting and converting your operational data into CO2e (carbon dioxide equivalent) estimates, allowing you to spend more time analyzing your activities and taking actions to manage and reduce your environmental impact.

Operational data can be generated from any actions that result in greenhouse gas emissions, including vehicle rides, energy consumption, flights, logistical operations, manufacturing, agriculture, heating, cooling, and countless other daily activities.

Using the Climatiq REST API, you can collect data from your software and systems, and automatically transform that data into CO2e values, using verified scientific data and methodologies.

Getting Started

The Climatiq API is designed to help developers build tools to automate reductions in their organizations' carbon footprint.

The API is organized around REST. It has predictable resource-oriented URLs; accepts JSON-encoded request bodies; returns JSON-encoded responses; and uses standard HTTP response codes, authentication, and verbs. To help maintain security, all requests must be made over HTTPS. Calls made over plain HTTP will fail.

Base URL

https://beta.api.climatiq.io

Select Emission Factor

An emission factor is a value that relates the quantity of a pollutant released to the atmosphere with a particular activity.

For example:

  • grid-mix: Energy consumed using grid electricity, measured in kWh.
  • flight-domestic: Domestic airplane flight, calculated using distance or airport codes.
  • articulated-truck: Transportation with an articulated truck, measured using weight and distance.

Authentication

Authenticate the app using API keys as bearer tokens. Always provide the Authorization header containing your API KEY as bearer token:

Authorization: Bearer <API_KEY>

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 or through client-side code. When possible, encrypt API keys when you store them.

Content-Type

To send data to our API, send the content-type header to application/json.

Content-Type: application/json

Errors

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

Status Codes

200 OK: Everything worked as expected.

400 Bad Request: The request was unacceptable, probably due to missing a required parameter.

401 Unauthorized: No valid API key was provided.

404 Not Found: The requested resource doesn't exist.

5xx Server Errors: Something went wrong on our servers.

Emission Factors

GET List all available emission factors—or query with parameters such category, source, region, or year—to help determine what emission factor should be used in your estimation.

https://beta.api.climatiq.io/emission-factors

Request

  • categorystring

    Filters by emission factor category. Defaults to all

    Optional
  • sourcestring

    Filters emission factors by data source

    Optional
  • regionstring

    Filters emission factors by region. Defaults to all

    Optional
  • yearnumber

    Filters emission factors by year. Defaults to all

    Optional

Response

The response includes a list of emission factors filtered by the request parameters above.

[
{
"id": "string",
"category": "string",
"source": "string",
"year": "string",
"region": "string",
"description": "string"
}
]

Estimate

POST Calculate estimated emissions in KgCO2 for a particular activity using the available emission factors. All requests are performed sending a POST request to the following endpoint:

https://beta.api.climatiq.io/estimate

You will find more specific examples for the following sectors below: Energy, Vehicle, Travel, Transport, Fuel, Water, Waste, and Accommodation.

Request

The following parameters can be defined as JSON-encoded body.

  • emission_factorobject | string

    Emission Factor ID or selection parameters. See below for more details.

    Required
  • parametersobject

    Emission factor parameters. See below for more details.

    Required
  • persistboolean

    Persist the estimate to the Analytics Dashboard. Default is true.

    Optional
  • metadataobject

    Provide optional metadata when persisting the estimate. See below for more details.

    Optional

Emission Factor Selection

We collect, normalize, and organize emission factors by source, region, and year, allowing for a granular selection of the relevant methodologies.

If no particular methodology is selected, the most conservative one will be automatically selected, representing the highest emitting emission factor.

"emission_factor": "string"
// or
"emission_factor": {
"id": "string",
"source": "string",
"region": "string",
"year": "string"
}

Parameters

Every emission factor category can accept different parameters. Check emission factors by sector for more details.

"parameters": {
"distance": "number",
"weight": "number",
"amount": "number"
}

Persistence

On every request, estimations can be persisted or volatile, depending on the value of the persist parameter.

true (default): emission estimates are stored in our analytics database and used for emission tracking, reporting, and other features.

false: emission estimates are not stored. This calculation can be used for displaying the resulting emission or stored in your own data storage.

"persist": boolean,

Metadata

While metadata is automatically calculated where possible, it can be overwritten with custom values. Currently only category will be populated while tags and scope will be empty unless a value is provided.

"metadata": {
"scope": "1" | "2" | "3",
"category": "string",
"tags": "string[]",
}

Metadata Parameters

  • scopestring

    Emission scope according to the GHG Protocol. Possible values are "1", "2," and "3". Default is "unknown."

    Optional
  • categorystring

    Emission category. Default is the emission factor category.

    Optional
  • tagsstring[]

    Emission tags. Array of strings representing tags.

    Optional

Estimation Request Body Types

{
"emission_factor": "string" | {
"id": "string",
"source": "string",
"region": "string",
"year": "string"
},
"parameters": {
"distance": number,
"weight": number
},
"persist": boolean,
"metadata": {
"scope": "1" | "2" | "3",
"category": "string",
"tags": "string[]",
}
}

Response Types

The response includes the selected emission factor and the total amount of emissions in kgCO2e.

{
"co2e": number,
"id": "string",
"source": "string",
"year": "string",
"region": "string",
"category": "string",
"value": number
}

Energy

Calculate emissions generated by energy consumption.

Parameters

  • amountnumber

    Total amount of energy consumed in kilowatt-hour (kwh)

    Required

Energy Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "grid-mix",
"parameters": {
"amount": 100
}
}'

Energy Emission Factors

idsourceregionyear
grid-mixgemis-4.95DE2015
ubaDE2017
gemis-4.95DE2020
DEFRAUK2019
EPAUS2018
BEISUK2019
gasBEISUK2019
solar-multigemis-4.94DE-
solar-monogemis-4.94DE-
remote-heatinggemis-4.95DE-
greenENWGDE-

Vehicle

Calculate emissions generated by a vehicle over a distance.

Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • route*string[]

    List of locations as ZIP codes.

    Optional
* planned feature

Vehicle Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "small-petrol-car",
"parameters": {
"distance": 100
}
}'

Vehicle Emission Factors

idsourceregionyear
petrol-carDEFRAUK2019
BEISUK2019
small-petrol-cargemis-5DE-
DEFRAUK2019
medium-petrol-cargemis-5DE-
DEFRAUK2019
heavy-petrol-cargemis-5DE-
DEFRAUK2019
diesel-carDEFRAUK2019
BEISUK2019
small-diesel-cargemis-5DE-
DEFRAUK2019
medium-diesel-cargemis-5DE-
DEFRAUK2019
heavy-diesel-cargemis-5DE-
DEFRAUK2019
carEPAUS2018
light-duty-truckEPAUS2018
medium-duty-truckEPAUS2018
heavy-duty-truckEPAUS2018
taxiDEFRAUK2019
jet-smallBEISUK2019
jet-largeBEISUK2019

Road Travel

Calculate emissions generated by road travel.

Road Travel Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • route*string[]

    List of locations as ZIP codes.

    Optional
* planned feature

Road Travel Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "bus",
"parameters": {
"distance": 100
}
}'

Road Travel Emission Factors

idsourceregionyear
busgemis-4.95DE-
DEFRAUK2019
EPAUS2018
coachDEFRAUK2019

Air Travel

Calculate emissions generated by air travel.

Air Travel Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • route*string[]

    List of locations as airport codes.

    Optional
* planned feature

Air Travel Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "flight-domestic",
"parameters": {
"distance": 500
}
}'

Air Travel Emission Factors

idsourceregionyear
flight-domesticDEFRAUK2019
flight-short-haulgemis-4.95DE-
DEFRAUK2019
EPAUS2018
flight-short-haul-economyDEFRAUK2019
flight-short-haul-businessDEFRAUK2019
flight-medium-haulEPAUS2018
flight-long-haulgemis-4.95DE-
DEFRAUK2019
EPAUS2018
flight-long-haul-economyDEFRAUK2019
flight-long-haul-businessDEFRAUK2019
flight-internationalDEFRAUK2019

Rail Travel

Calculate emissions generated by rail travel.

Rail Travel Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • route*string[]

    List of locations as ZIP codes.

    Optional
* planned feature

Rail Travel Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "underground",
"parameters": {
"distance": 20
}
}'

Rail Travel Emission Factors

idsourceregionyear
train-electric-longgemis-4.95DE-
train-electric-shortgemis-4.95DE-
train-diesel-longgemis-4.95DE-
train-diesel-shortgemis-4.95DE-
train-shortDEFRAUK2019
EPAUS2018
train-longDEFRAUK2019
EPAUS2018
tramDEFRAUK2019
EPAUS2018
undergroundDEFRAUK2019
BEISUK2019
EPAUS2018

Sea Travel

Calculate emissions generated by sea travel.

Sea Travel Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • route*string[]

    List of locations as port codes.

    Optional
* planned feature

Sea Travel Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "ferry",
"parameters": {
"distance": 20
}
}'

Sea Travel Emission Factors

idsourceregionyear
ferryBEISUK2019

Road Transport

Calculate emissions generated by road transport.

Road Transport Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • weightnumber

    Total weight transported in kilograms (kg).

    Required
  • route*string[]

    List of locations as ZIP codes.

    Optional
* planned feature

Road Transport Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "articulated-truck",
"parameters": {
"distance": 300,
"weight": 100
}
}'

Road Transport Emission Factors

idsourceregionyear
small-diesel-truckgemis-5DE-
DEFRAUK2019
medium-diesel-truckgemis-5DE-
DEFRAUK2019
heavy-diesel-truckgemis-5DE-
DEFRAUK2019
small-cng-truckgemis-5DE-
medium-cng-truckgemis-5DE-
articulated-truckgemis-5DE-
DEFRAUK2019
light-articulated-truckDEFRAUK2019
heavy-articulated-truckDEFRAUK2019

Air Transport

Calculate emissions generated by air transport.

Air Transport Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • weightnumber

    Total weight transported in kilograms (kg).

    Required
  • route*string[]

    List of locations as airport codes.

    Optional
* planned feature

Air Transport Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "freight-plane-domestic",
"parameters": {
"distance": 500,
"weight": 100
}
}'

Air Transport Emission Factors

idsourceregionyear
freight-planeEPAUS2018
freight-plane-domesticgemis-5DE-
DEFRAUK2019
freight-plane-short-haulDEFRAUK2019
freight-plane-long-haulDEFRAUK2019
freight-plane-internationalgemis-5DE-
DEFRAUK2019

Rail Transport

Calculate emissions generated by rail transport.

Rail Transport Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • weightnumber

    Total weight transported in kilograms (kg).

    Required
  • route*string[]

    List of locations as ZIP codes.

    Optional
* planned feature

Rail Transport Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "freight-train",
"parameters": {
"distance": 500,
"weight": 100
}
}'

Rail Transport Emission Factors

idsourceregionyear
freight-train-electricgemis-5DE-
freight-train-dieselgemis-5DE-
freight-trainDEFRAUK2019
EPAUS2018

Sea Transport

Calculate emissions generated by sea transport.

Sea Transport Parameters

  • distancenumber

    Total distance in kilometers (km).

    Required
  • weightnumber

    Total weight transported in kilograms (kg).

    Required
  • route*string[]

    List of locations as port codes.

    Optional
* planned feature

Sea Transport Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "container-ship",
"parameters": {
"distance": 500,
"weight": 100
}
}'

Sea Transport Emission Factors

idsourceregionyear
container-shipgemis-5DE-
DEFRADE2019
freight-shipgemis-5DE-
DEFRAUK2019
bulk-carrier-shipDEFRAUK2019
diesel-shipgemis-5DE-
crude-tankerDEFRAUK2019

Fuel

Calculate emissions generated by fuel consumption.

Fuel Parameters

  • amountnumber

    Total amount of fuel consumed liters (L).

    Required

Fuel Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "diesel",
"parameters": {
"amount": 10
}
}'

Fuel Emission Factors

idsourceregionyear
dieselgemis-5DE-
DEFRAUK2019
BEISUK2019
petrolgemis-5DE-
DEFRAUK2019
BEISUK2019
cnggemis-5DE-
DEFRAUK2019
DEFRAUK2019
lpggemis-5DE-
DEFRAUK2019
DEFRAUK2019
BEISUK2019
oilBEISUK2019
biodieselBEISUK2019

Water

Calculate emissions generated by water consumption.

Water Parameters

  • amountnumber

    Total amount of water in cubic meters (m3).

    Required

Water Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "water-used",
"parameters": {
"amount": 10
}
}'

Water Emission Factors

idsourceregionyear
useBEISUK2019
wasteBEISUK2019

Waste

Calculate emissions generated by waste treatment.

Parameters

  • weightnumber

    Total amount of waste in kilograms (kg).

    Required

Waste Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "landfill",
"parameters": {
"weight": 100
}
}'

Waste Emission Factors

idsourceregionyear
landfillBEISUK2019
recycledBEISUK2019
energyBEISUK2019
compostedBEISUK2019

Accomodation

Calculate emissions generated by a hotel stay.

Parameters

  • amountnumber

    Amount of nights per guest.

    Required

Request Example

curl --request POST \
--url 'https://beta.api.climatiq.io/estimate' \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"emission_factor": "hotel-night",
"parameters": {
"amount": 7
}
}'

Accomodation Emission Factors

idsourceregionyear
hotel-nightBEISUK2019