Travel Endpoint version: V1 (preview 1)V1 (preview 1) ADD-ONADD-ON

⚠️

Preview Feature

This feature is currently in preview. That means that we believe the feature is good enough to start using, but:

There might still be bugs or edge cases we haven't covered.
The documentation and error messages might be less detailed.
We might need to make further changes in the API surface.

We need the ability to iterate quickly on preview versions, so we offer less guarantees of stability. When we make changes to the preview version, we will release a new version, and you must migrate to this new version within three months. Read more about API versioning at Climatiq here.For this reason, preview endpoints are not available without explicitly opting in. If you would like to opt-in to this preview feature, please contact us.

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

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://preview.api.climatiq.io/travel/v1-preview1/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

Request parametersShould be sent as a JSON object in the body

travel_moderequired string
The primary type of travel for this journey. Valid values are: air, car, rail.
originrequired object
The origin of the journey. Accepts QueryLocation, IataCodeLocation, UNLocodeLocation or CoordinateLocation.
destinationrequired object
The destination of the journey. Accepts QueryLocation, IataCodeLocation, UNLocodeLocation or CoordinateLocation.
yearinteger
Default value: Latest year available
The year that the travel occurred.
Default Value
Latest year available
distance_kmfloat
If you have an actual distance for this leg in kilometers you can input the distance here. Climatiq will then use this distance instead of the planned distance it would normally calculate.
car_detailsobject
Additional 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.
air_detailsobject
Additional 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.

Car Sizes

The car_details 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 size	Petrol	Diesel	Others	Car example
`small`	below 1.4-liter engine	below 1.7-liter engine	Vehicle 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.
`medium`	from 1.4-liter to 2.0-liter engine	from 1.7-liter to 2.0-liter engine	Vehicle models of a similar size (i.e. generally market segment C)	Volkswagen Golf, Honda Civic etc.
`large`	above 2-liter engine	above 2-liter engine	Vehicle models of a similar size (i.e. generally market segment D and above)	BMW 3-Series, Volkswagen Passat etc.

curl --request POST \
  --url https://preview.api.climatiq.io/travel/v1-preview1/distance \
  --header "Authorization: Bearer $CLIMATIQ_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.

Response parameters

co2efloat
The total co2e emitted by the journey, expressed in co2e_unit.
co2e_unitstring
Always kg.
co2e_calculation_methodstring
Which calculation methodology that was used for the calculation. The value of this is either ipcc_ar4_gwp100, ipcc_ar5_gwp100, ipcc_ar6_gwp100 or ipcc_mixed_gwp100. <br/> Learn more about calculation methods here.
distance_kmfloat
The distance in kilometers of the journey using the primary mode of transport (excludes any travel to and from airport or railway stations).
originobject
A ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your origin parameter.
destinationobject
A ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your destination parameter.
direct_emissionsobject
The 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_emissionsobject
The 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).
noticesarray of Notices
Any notices related to the calculation.
source_trailarray of SourceDataPoint
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail. This field is deprecated - please use the source_trail inside the direct_emissions and indirect_emissions fields.

{
    "co2e": 44.25,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ipcc_mixed_gwp100",
    "source_trail": [
        {
            "data_category": "emission_factor",
            "name": "Electricity supplied from grid - production mix",
            "source": "AIB",
            "source_dataset": "European Residual Mix",
            "year": "2022",
            "region": "DE",
            "region_name": "Germany"
        },
        {
            "data_category": "emission_factor",
            "name": "Petrol (100% mineral petrol)",
            "source": "BEIS",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2023",
            "year": "2023",
            "region": "GB",
            "region_name": "United Kingdom"
        }
    ],
    "distance_km": 299,
    "origin": {
        "name": "Hamburg",
        "latitude": 53.51666,
        "longitude": 9.93333,
        "confidence_score": null
    },
    "destination": {
        "name": "Berlin, Germany",
        "latitude": 52.51604,
        "longitude": 13.37691,
        "confidence_score": 1
    },
    "direct_emissions": {
        "co2e": 34.24,
        "co2e_unit": "kg",
        "source_trail": [
            {
                "data_category": "emission_factor",
                "name": "Electricity supplied from grid - production mix",
                "source": "AIB",
                "source_dataset": "European Residual Mix",
                "year": "2022",
                "region": "DE",
                "region_name": "Germany"
            },
            {
                "data_category": "emission_factor",
                "name": "Petrol (100% mineral petrol)",
                "source": "BEIS",
                "source_dataset": "Greenhouse gas reporting: conversion factors 2023",
                "year": "2023",
                "region": "GB",
                "region_name": "United Kingdom"
            }
        ]
    },
    "indirect_emissions": {
        "co2e": 10.01,
        "co2e_unit": "kg",
        "source_trail": [
            {
                "data_category": "emission_factor",
                "name": "Electricity supplied from grid - production mix",
                "source": "AIB",
                "source_dataset": "European Residual Mix",
                "year": "2022",
                "region": "DE",
                "region_name": "Germany"
            },
            {
                "data_category": "emission_factor",
                "name": "Petrol (100% mineral petrol)",
                "source": "BEIS",
                "source_dataset": "Greenhouse gas reporting: conversion factors 2023",
                "year": "2023",
                "region": "GB",
                "region_name": "United Kingdom"
            }
        ]
    },
    "notices": []
}

Spend-based method

POST This endpoint uses EXIOBASE emission factors to calculate emissions based on your spending on travel activities in any currency. This endpoint automatically takes inflation into account, if the year you spent the money was different than the year of the emission factor. Note that the EXIOBASE spend-based emission factor, used for the road travel is, in fact, an average emission factor for a mix of different types of transport: urban and suburban passenger land transport, taxi operation, other passenger land transport and freight transport by road and can therefore produce results of lower accuracy. Climatiq advises to use fuel-based or distance-based method, where possible.

https://preview.api.climatiq.io/travel/v1-preview1/spend

Request

Request parametersShould be sent as a JSON object in the body

spend_typerequired string
The type of travel associated with the expenditure. Valid values are: air, road, rail, sea, and hotel.
moneyrequired float
The amount of money spent.
money_unitrequired string
The currency in which the money unit is expressed.
spend_locationrequired object
The location where money was spent. Accepts QueryLocation, IataCodeLocation, UNLocodeLocation or CoordinateLocation.
spend_yearinteger
Default value: Latest year available
The year in which expenditures occurred.
Default Value
Latest year available

curl --request POST \
  --url https://preview.api.climatiq.io/travel/v1-preview1/spend \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
    "spend_type": "air",
    "money": 100,
    "money_unit": "gbp",
    "spend_location": {
        "locode": "GB-LON"
    },
    "spend_year": 2018
}'

Response

Response parameters

co2efloat
co2e emitted by the journey, expressed in co2e_unit.
co2e_unitstring
Always kg.
co2e_calculation_methodstring
Which calculation methodology that was used for the calculation. The value of this is either ipcc_ar4_gwp100, ipcc_ar5_gwp100, ipcc_ar6_gwp100 or ipcc_mixed_gwp100. <br/> Learn more about calculation methods here.
spend_locationobject
A ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your spend_location parameter.
noticesarray of Notices
Any notices related to the calculation.
source_trailarray of SourceDataPoint
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail.

{
    "co2e": 135.5,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ipcc_ar5_gwp100",
    "source_trail": [
        {
            "data_category": null,
            "name": "Country-specific inflation rates",
            "source": "World Bank",
            "source_dataset": null,
            "year": null,
            "region": "GB",
            "region_name": "United Kingdom"
        },
        {
            "data_category": "emission_factor",
            "name": "Air transport services",
            "source": "EXIOBASE",
            "source_dataset": "EXIOBASE 3",
            "year": "2019",
            "region": "GB",
            "region_name": "United Kingdom"
        }
    ],
    "spend_location": {
        "name": "London, LND, GB",
        "latitude": 51.50643,
        "longitude": -0.12718,
        "confidence_score": null
    },
    "notices": []
}

Hotels

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://preview.api.climatiq.io/travel/v1-preview1/hotel

Request

Request parametersShould be sent as a JSON object in the body

hotel_nightsrequired integer
The number of nights spent in the hotel.
locationrequired object
The location of the hotel. Accepts QueryLocation, IataCodeLocation, UNLocodeLocation or CoordinateLocation.
yearinteger
Default value: Latest year available
The year that the hotel stay occurred.
Default Value
Latest year available

curl --request POST \
  --url https://preview.api.climatiq.io/travel/v1-preview1/hotel \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
    "hotel_nights": 5,
    "location": {
        "query": "San Francisco"
    }
}'

Response

Response parameters

co2efloat
co2e emitted by the hotel stay, expressed in co2e_unit.
co2e_unitstring
Always kg.
co2e_calculation_methodstring
Which calculation methodology that was used for the calculation. The value of this is either ipcc_ar4_gwp100, ipcc_ar5_gwp100, ipcc_ar6_gwp100 or ipcc_mixed_gwp100. <br/> Learn more about calculation methods here.
noticesarray of Notices
Any notices related to the calculation.
locationobject
A ResponseLocation containing the name and an (optional) confidence_score of the location we found, given your location parameter.
source_trailarray of SourceDataPoint
A list of Source Data Points that help explain and provide trust in the calculation. Click to view more details about Source Trail.

{
    "co2e": 80.5,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ipcc_ar5_gwp100",
    "source_trail": [
        {
            "data_category": "emission_factor",
            "name": "Hotel stay",
            "source": "BEIS",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2024",
            "year": "2024",
            "region": "US",
            "region_name": "United States of America (the)"
        }
    ],
    "location": {
        "name": "United States of America (the)",
        "confidence_score": 1
    },
    "notices": []
}

Response Location

Many endpoints return locations back to you. These locations 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 float 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`.

Notice

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 value	description
`partial_inflation_adjustment`	Inflation adjustment was applied only partially, not covering the entire period.
`no_inflation_adjustment`	No 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_fallback`	Factors 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_fallback`	It was not possible to find a route given the current parameters. A different routing mechanism was used instead.

Custom Mappings Autopilot