Skip to Content
API ReferenceTravelTravel v1

Travel Endpoint version: V1V1

To see the changes since the preview versions, see our changelog

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.

Depending on what data you have available for your travels, you should use different parts of Climatiq:

  • If you have a primary transportation mode, and the distance traveled, you should use the travel endpoint: Distance-based travel
  • If you have data about the hotel nights spent during a travel, use the travel endpoint: Hotels.
  • If you have fuel usage data, which is generally the most precise, you can use Basic Estimate if you want to select the emission factor yourself, or the Fuel Use endpoint inside the Energy Feature.
  • If you only have spend-based data, we recommend that you use Mapping Agent to find an appropriate spend-based emission factors for your travel. However, spend-based data is generally fairly unreliable for travel emissions.

Distance-based Travel

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://api.climatiq.io/travel/v1/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  (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 headersRequired HTTP headers for this request
    • Authorizationrequired string
      Bearer token containing your Climatiq API key. Example: Authorization: Bearer CLIMATIQ_API_KEY
      Don't have an API key? Get your API key here.
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 Location String, Query Location, IATA Code Location, UN/LOCODE Location or Coordinate Location

    • destinationrequired object

      The destination of the journey. Accepts Location String, Query Location, IATA Code Location, UN/LOCODE Location or Coordinate Location

    • yearinteger
      Default value: Latest year available

      The year that the travel occurred.

    • 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 sizePetrolDieselOthersCar example
smallbelow 1.4-liter enginebelow 1.7-liter engineVehicle models of a similar size (i.e. market segment A or B )Fiat 500, Opel Adam, Renault Clio, Ford Fiesta etc.
mediumfrom 1.4-liter to 2.0-liter enginefrom 1.7-liter to 2.0-liter engineVehicle models of a similar size (i.e. generally market segment C)Volkswagen Golf, Honda Civic etc.
largeabove 2-liter engineabove 2-liter engineVehicle models of a similar size (i.e. generally market segment D and above)BMW 3-Series, Volkswagen Passat etc.
curl --request POST \
  --url https://api.climatiq.io/travel/v1/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": 41.77891251,
    "co2e_unit": "kg",
    "co2e_calculation_method": "ipcc_ar5_gwp100",
    "source_trail": [
        {
            "data_category": null,
            "name": "Derived average energy & fuel used per driven km for hybrid car: average",
            "source": "BEIS",
            "source_dataset": null,
            "year": null,
            "region": "",
            "region_name": "",
            "id": null
        },
        {
            "data_category": "emission_factor",
            "name": "Electricity supplied from grid",
            "source": "UBA",
            "source_dataset": "Entwicklung der spezifischen Treibhausgas-Emissionen des deutschen Strommix in den Jahren 1990 - 2023",
            "year": "2023",
            "region": "DE",
            "region_name": "Germany",
            "id": "c8c06d6b-9457-4e84-9256-0717cc604013"
        },
        {
            "data_category": "emission_factor",
            "name": "Electricity supplied from grid",
            "source": "UBA",
            "source_dataset": "Entwicklung der spezifischen Treibhausgas-Emissionen des deutschen Strommix in den Jahren 1990 - 2023",
            "year": "2023",
            "region": "DE",
            "region_name": "Germany",
            "id": "da2cd1a5-44b5-404c-b285-9f418c4d0f4c"
        },
        {
            "data_category": "emission_factor",
            "name": "Electricity supplied from grid: T&D losses",
            "source": "UBA",
            "source_dataset": "Entwicklung der spezifischen Treibhausgas-Emissionen des deutschen Strommix in den Jahren 1990 - 2023",
            "year": "2023",
            "region": "DE",
            "region_name": "Germany",
            "id": "a30a504d-e24c-4d1c-b4df-7d61816fa183"
        },
        {
            "data_category": "emission_factor",
            "name": "Petrol - 100% mineral petrol",
            "source": "BEIS",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2024",
            "year": "2024",
            "region": "GB",
            "region_name": "United Kingdom",
            "id": "5e8f99c1-57cf-4235-8b96-988ea5539020"
        },
        {
            "data_category": "emission_factor",
            "name": "Petrol - 100% mineral petrol",
            "source": "BEIS",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2024",
            "year": "2024",
            "region": "GB",
            "region_name": "United Kingdom",
            "id": "dcbf18c2-fe21-4bf6-af4b-a641d8877dad"
        }
    ],
    "distance_km": 299.108,
    "origin": {
        "name": "Hamburg",
        "latitude": 53.51666,
        "longitude": 9.93333,
        "confidence_score": null
    },
    "destination": {
        "name": "Berlin, Germany",
        "latitude": 52.51603,
        "longitude": 13.37699,
        "confidence_score": 1
    },
    "direct_emissions": {
        "co2e": 33.6584324091,
        "co2e_unit": "kg",
        "source_trail": [
            {
                "data_category": "emission_factor",
                "name": "Electricity supplied from grid",
                "source": "UBA",
                "source_dataset": "Entwicklung der spezifischen Treibhausgas-Emissionen des deutschen Strommix in den Jahren 1990 - 2023",
                "year": "2023",
                "region": "DE",
                "region_name": "Germany",
                "id": "da2cd1a5-44b5-404c-b285-9f418c4d0f4c"
            },
            {
                "data_category": "emission_factor",
                "name": "Petrol - 100% mineral petrol",
                "source": "BEIS",
                "source_dataset": "Greenhouse gas reporting: conversion factors 2024",
                "year": "2024",
                "region": "GB",
                "region_name": "United Kingdom",
                "id": "5e8f99c1-57cf-4235-8b96-988ea5539020"
            }
        ]
    },
    "indirect_emissions": {
        "co2e": 8.12048010092,
        "co2e_unit": "kg",
        "source_trail": [
            {
                "data_category": "emission_factor",
                "name": "Electricity supplied from grid",
                "source": "UBA",
                "source_dataset": "Entwicklung der spezifischen Treibhausgas-Emissionen des deutschen Strommix in den Jahren 1990 - 2023",
                "year": "2023",
                "region": "DE",
                "region_name": "Germany",
                "id": "c8c06d6b-9457-4e84-9256-0717cc604013"
            },
            {
                "data_category": "emission_factor",
                "name": "Electricity supplied from grid",
                "source": "UBA",
                "source_dataset": "Entwicklung der spezifischen Treibhausgas-Emissionen des deutschen Strommix in den Jahren 1990 - 2023",
                "year": "2023",
                "region": "DE",
                "region_name": "Germany",
                "id": "da2cd1a5-44b5-404c-b285-9f418c4d0f4c"
            },
            {
                "data_category": "emission_factor",
                "name": "Electricity supplied from grid: T&D losses",
                "source": "UBA",
                "source_dataset": "Entwicklung der spezifischen Treibhausgas-Emissionen des deutschen Strommix in den Jahren 1990 - 2023",
                "year": "2023",
                "region": "DE",
                "region_name": "Germany",
                "id": "a30a504d-e24c-4d1c-b4df-7d61816fa183"
            },
            {
                "data_category": "emission_factor",
                "name": "Petrol - 100% mineral petrol",
                "source": "BEIS",
                "source_dataset": "Greenhouse gas reporting: conversion factors 2024",
                "year": "2024",
                "region": "GB",
                "region_name": "United Kingdom",
                "id": "dcbf18c2-fe21-4bf6-af4b-a641d8877dad"
            }
        ]
    },
    "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://api.climatiq.io/travel/v1/hotel

Request

Request headersRequired HTTP headers for this request
    • Authorizationrequired string
      Bearer token containing your Climatiq API key. Example: Authorization: Bearer CLIMATIQ_API_KEY
      Don't have an API key? Get your API key here.
Request parametersShould be sent as a JSON object in the body
curl --request POST \
  --url https://api.climatiq.io/travel/v1/hotel \
  --header "Authorization: Bearer $CLIMATIQ_API_KEY" \
  --data '{
    "hotel_nights": 5,
    "location": "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 2025",
            "year": "2025",
            "region": "US",
            "region_name": "United States of America (the)",
            "id": "5a8c1cd3-bbc9-49d4-87bd-b1102e3866ae"
        }
    ],
    "location": {
        "name": "California, US",
        "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 Query Location, or a Location String with a query..

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 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.

FAQ

Why are my air travel emissions higher than calculations from other places?

There are several reasons why Climatiq’s air travel emissions may appear higher than other calculations. We use UK Government BEIS emission factors which include a radiative forcing (RF) multiplier that accounts for the additional climate impact of flying beyond just CO2 emissions. This includes non-CO2 effects like water vapor, contrails, and NOx emissions that add approximately 90% to the direct fuel combustion impact. Additionally, the BEIS factors include an 8% distance uplift for non-direct routing and use class-specific factors (economy vs business vs first class) which can significantly affect the results. Other calculators may use different emission factors, older data, or exclude the radiative forcing effect entirely.

What is radiative forcing and when should I include it?

Radiative forcing captures the additional climate impact of aviation beyond direct CO2 emissions. When aircraft burn fuel at altitude, they produce water vapor, contrails, and nitrogen oxides that have warming effects beyond the CO2 released. The UK Government methodology we use includes this effect by default, increasing aviation emissions by approximately 90%. While this is considered best practice for most carbon accounting, some reporting standards may not require, or even prohibit it.

This endpoint does currently not support excluding radiative forcing.

How does the API determine flight distances?

For air travel, the API automatically calculates great circle distances between the two airports closest to your origin and destination.

How does the API determine flight classification?

A flight being classified as either domestic, short, or long haul determines the emissions intensity per km, with shorter flights generally being more intensive per kilometer traveled. We use the classification from the UK government, where:

  • Any flight less than 483km, or inside the UK is considered domestic
  • Flights between 483-3700km are considered short-haul
  • Any flight over 3700km is considered long-haul

Can I calculate emissions for multi-leg journeys or return trips?

The distance-based endpoint calculates emissions for one-way travel with a single primary mode of transport. For multi-leg journeys (like flights with connections) or return trips, you need to make separate API calls for each leg. The API doesn’t automatically calculate emissions for e.g. transfers to/from airports or train stations. If you expect these additional legs to be important, you should call the API again to calculate them separately.

What if I only have spend-based data

Spend-based data is generally fairly unreliable for estimating travel emissions, but if you only have spend-based data, we recommend that you use the Mapping Agent to find an appropriate spend-based emission factor for a given travel.

What about Taxi Trips?

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, if you only have a spend-amount, you can treat it as spend-based data, and have Mapping Agent attempt to find an appropriate emission factor.

Last updated on
TravelTravel v1 (preview3)