API Reference
Travel

Travel ADD-ONADD-ON

Climatiq provides a comprehensive toolkit to help businesses measure GHG emissions from travel activities. This includes reporting scope 3.6 emissions under the GHG Protocol for travel activities in vehicles owned or operated by third parties, such as aircraft, trains and passenger cars. Emissions associated with hotel stays can also be calculated, providing a comprehensive view of travel-related emissions.

The GHG Protocol outlines three main methods for calculating GHG emissions from your travels:

  • Fuel-based
  • Distance-based
  • Spend-based

Your choice of method will depend on the data you have at hand.

Our endpoints are tailored to handle all possible situations with respect to your data availability. Use our spend-based endpoint if you only have expenditure data available. For enhanced accuracy, the distance-based endpoint offers route-specific estimates, automatic distance calculations, and customization options to improve calculations.

Notes on calculation methods:

  • The Travel feature provides endpoints for distance-based and spend-based approaches where you have distance or spend data.
  • If you have fuel usage data (e.g. liters of petrol), use our Estimate endpoint or Energy feature.
  • To calculate emissions from taxi journeys, use the distance-based method when you have data on the vehicle type and the journey's origin and destination. Alternatively, use the spend-based method if you know the cost of the taxi.

Distance-based method ALPHAALPHA

POST This endpoint allows you to apply the distance-based method by specifying the origin and destination of your journey, and the primary mode of transportation: by air, car, or rail. The journey distance is automatically determined and used for the calculation.

The endpoint will return the CO2e for the primary mode of transportation. If the journey includes separate legs (e.g. travel to / from a railway station or airport) then these need to be calculated separately with additional calls to the API.

https://beta4.api.climatiq.io/travel/distance
Notes
  • The endpoint works for one-way travel for one passenger. If your journey has more legs (e.g. is a return journey / round trip) or passengers, you should make multiple API calls.
  • We do not have full coverage of the global rail network. If data on specific rail segments is missing, we might use car routes for distance calculations instead of rail routes.
  • For air travel, the endpoint will always include a Radiative Forcing (opens in a new tab) (RF) multiplier. It is best practice to include the RF multiplier in most reporting although sometimes (e.g. under the SBTi) it is not accounted for.
  • For electricity-based estimates, such as electric vehicles, the CO2e values returned are location-based, not market-based. Find more details on the different types of electricity-based estimates in our Energy feature.

Request

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

NameTypeDescriptionRequired
travel_modeStringThe primary type of travel for this journey. Valid values are: air, car, rail.yes
originLocationThe origin of the journey. Accepts QueryLocation, IataCodeLocation, UNLocodeLocation or CoordinateLocation.yes
destinationLocationThe destination of the journey. Accepts QueryLocation, IataCodeLocation, UNLocodeLocation or CoordinateLocation.yes
yearNumberThe year that the travel occurred.No, defaults to current year
car_detailsCarDetailsAdditional details about the car used for the travel. Supplying this will result in more accurate estimations. Can only be used when travel_mode is car.no
air_detailsAirDetailsAdditional details about the plane used for the travel. Supplying this will result in more accurate estimations. Can only be used when travel_mode is air.no

Car Details

NameDescriptionRequired
car_sizeHow big is the car? Valid values are small, medium, large, and average. See the table below for more details.No, defaults to average
car_typeWhich type of car is it? Valid values are: petrol, diesel, hybrid (cars with a battery that is recharged by the internal combustion engine), plugin_hybrid, (cars with an internal combustion engine and a battery that can be plugged in), electric and average.No, defaults to average
Car Sizes

The CarDetails object allows you to specify different car types that you can see in the list below. If you don't know the size of the car used for the trip, you can omit the car_size or set it as average, both of which will result in a weighted average of car sizes on the road being used.

Car sizePetrolDieselOthersCar example
smallbelow 1.4-litre enginebelow 1.7-litre engineVehicle models of a similar size (i.e. market segment A or B (opens in a new tab))Fiat 500, Opel Adam, Renault Clio, Ford Fiesta etc.
mediumfrom 1.4-litre to 2.0-litre enginefrom 1.7-litre to 2.0-litre engineVehicle models of a similar size (i.e. generally market segment C)Volkswagen Golf, Honda Civic etc.
largeabove 2-litre engineabove 2-litre engineVehicle models of a similar size (i.e. generally market segment D and above)BMW 3-Series, Volkswagen Passat etc.

Air Details

NameDescriptionRequired
classThe cabin class of the flight. Options are: economy, first, business and average which you should use if you do not know the class.No, defaults to average
curl --request POST \
--url https://beta4.api.climatiq.io/travel/distance \
--header 'Authorization: Bearer API_KEY' \
--data '{
"origin": {
"locode": "DE-HAM"
},
"destination": {
"query": "Berlin"
},
"travel_mode": "car",
"car_details": {
"car_type": "plugin_hybrid"
}
}'

Response

A response consists of the following attributes.

NameDescription
co2eThe total co2e emitted by the journey, expressed in co2e_unit.
co2e_unitAlways kg
distance_kmThe distance in kilometers of the journey using the primary mode of transport (excludes any travel to and from airport or railway stations).
originA ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your origin parameter.
destinationA ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your destination parameter.
direct_emissionsThe emissions associated with the direct emissions of the journey, such as the combustion of fuel or generation of electricity. For air flights, the radiative forcing effect is included in these emissions.
indirect_emissionsThe upstream emissions associated with the journey, such as transmission and distribution losses for electricity, or the extraction and transportation of the fuel (i.e. well-to-tank).
noticesAny notices related to the calculation.
{
"co2e": 44.08159714181675,
"co2e_unit": "kg",
"distance_km": 297.801,
"origin": {
"name": "Hamburg",
"latitude": 53.516666666666666,
"longitude": 9.933333333333334,
"confidence_score": null
},
"destination": {
"name": "Berlin, Germany",
"latitude": 52.51604,
"longitude": 13.37691,
"confidence_score": 1
},
"direct_emissions": {
"co2e": 34.109217919368895,
"co2e_unit": "kg"
},
"indirect_emissions": {
"co2e": 9.972379222447856,
"co2e_unit": "kg"
},
"notices": []
}

Spend-based method ALPHAALPHA

POST This endpoint uses EXIOBASE emission factors to calculate travel emissions based on your spending on travel activities in any currency.

https://beta4.api.climatiq.io/travel/spend

Request

NameTypeDescriptionRequired
spend_typeStringThe type of travel associated with the expenditure. Valid values are: air, road, rail, sea, and hotel.yes
moneyNumberThe amount of money spent.yes
money_unitStringThe currency in which the money unit is expressed.yes
spend_locationObjectThe location where money was spent. Accepts QueryLocation, IataCodeLocation, UNLocodeLocation or CoordinateLocation.yes
spend_yearNumberThe year in which expenditures occurred.No, defaults to current year
curl --request POST \
--url https://beta4.api.climatiq.io/travel/spend \
--header 'Authorization: Bearer API_KEY' \
--data '{
"spend_type": "air",
"money": 100,
"money_unit": "gbp",
"spend_location": {
"locode": "GB-LON"
},
"spend_year": 2018
}'

Response

NameDescription
co2eco2e emitted by the journey, expressed in co2e_unit.
co2e_unitAlways kg
spend_locationA ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your spend_location parameter.
noticesAny notices related to the calculation.
{
"co2e": 135.5159392127085,
"co2e_unit": "kg",
"spend_location": {
"name": "London, LND, GB",
"confidence_score": null
},
"notices": []
}

Hotels ALPHAALPHA

POST Use this endpoint to estimate emissions from hotel stays across the world based on the number of nights spent. If no emission factor is available for hotels in the given country, another factor from the same continent is used.

https://beta4.api.climatiq.io/travel/hotel

Request

NameDescriptionRequired
hotel_nightsThe number of nights spent in the hotel.yes
locationThe location of the hotel. Accepts QueryLocation (opens in a new tab), IataCodeLocation (opens in a new tab), UNLocodeLocation (opens in a new tab) or CoordinateLocation (opens in a new tab).yes
yearThe year that the hotel stay occurred.No, defaults to current year
curl --request POST \
--url https://beta4.api.climatiq.io/travel/hotel \
--header 'Authorization: Bearer API_KEY' \
--data '{
"hotel_nights": 5,
"location": {
"query": "San Francisco"
}
}'

Response

NameDescription
co2eco2e emitted by the hotel stay, expressed in co2e_unit.
co2e_unitAlways kg
noticesAny notices related to the calculation.
locationA ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your location parameter.
{
"co2e": 80.5,
"co2e_unit": "kg",
"location": {
"name": "United States",
"confidence_score": 1
},
"notices": []
}

Location

Many of the endpoints accept a location. There are four different ways to input a location.

Query Location

Query Location AttributesRequired
query string
A free text query describing the location, such as "Berlin, Germany", or "10 Downing Street".
optional
country string
The two or three letter ISO-3166 country code (opens in a new tab) for a given location. If you want to find locations in China you must specify the correct country code.
optional
postal_code string
The postal (or zip) code for the given location. If used, country or query must also be specified.
optional

All the properties are optional, but you must specify at least a query or a country + postal_code. You may specify all three. Note that not all countries have support for postal codes, and the format might be different from country to country. See this table (opens in a new tab) for details on postal codes.

Locations in China

To specify locations in China, ensure you have added the country attribute to the location object and that it is set to CN or CHN.

IATA Code Location

IataLocation AttributesRequired
iata string
An IATA airport code.
required

UN/LOCODE Location

UNLocode Location AttributesRequired
locode string
An UN/LOCODE (opens in a new tab) of the format DE-BER for Berlin. The Locode must contain both country and location.
required

Coordinate Location

Coordinate Location AttributesRequired
longitude number
The longitude of the coordinate.
required
latitude number
The latitude of the coordinate.
required
country number
The 2-letter country code for the country that this coordinate is located within.
required

Response Location

The location that is returned to you in the API response will contain the following properties

Response Location attributes
name string
A human-readable name of the location.
latitude string or null
The latitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled.
longitude string or null
The longitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled.
confidence_score number
A confidence score between 0 and 1, determining how certain we are that the location matches your query. Only exists if the input location was a QueryLocation.

Notices

The notices array can contain these objects:

Notice attributes
severity string
Either warning or info. warning is for messages that might lead to inaccurate calculations. You should check these to make sure the results are fit for your intended purpose. info is for information that will help you understand the calculation result better.
message string
An explanation of the notice.
code string
A programmatic value you can use to disambiguate the different notice types.

The different possible values for code are as follows. You should not treat this list as exhaustive as more values may be added with time:

Notice code valuedescription
partial_inflation_adjustmentInflation adjustment was applied only partially, not covering the entire period.
no_inflation_adjustmentNo inflation adjustment was made to the procurement. This could be because there is no data for the spend_country or inflation data is missing for the entire period.
location_fallbackFactors or calculation methods for the exact location are not available, we have used a fallback location which we believe best covers the specified location.
routing_fallbackIt was not possible to find a route given the current parameters. A different routing mechanism was used instead.