# Overview
Guides to integrate SQUAKE's carbon APIs.
## Overview
In addition to our guides and documentation, we also offer a dedicated support page to assist you with any questions or issues you may encounter. Visit our [Support Page](https://support.squake.earth/) for detailed help, troubleshooting, and additional resources to get the most out of SQUAKE's services.
### :envelope\_with\_arrow: Contact Forms
Our contact forms are designed to help you communicate with us effectively. Whether you have feedback to share or need to report an incident, we've got you covered. Please use the appropriate form below:
* :envelope: [Contact Form](/feedback-form): Share your thoughts and suggestions about our services and processes, as well as get in contact with us.
* :warning: [Incident Form](/incident-form): Report any issues or incidents you've encountered, and our support team will respond as soon as possible.
### :file\_cabinet: API Requests & Responses
Our APIs are designed to be user-friendly and efficient, enabling smooth integration into your system. This section provides detailed documentation on how to make requests to our API, interpret responses, and handle data effectively. Whether you're just getting started or looking to optimize your usage, you'll find everything you need to successfully interact with our APIs.
### :new: Notable Changes
We continuously work to improve our services, and all notable updates and changes are documented in this section. Stay informed by reviewing the latest modifications to our offerings, including updates for accommodations, trains, flights, and environmental initiatives.
### :bulb: Use Cases
To help you get the most out of our services, we have documented various use cases that showcase how to utilize our offerings effectively:
* [Fulfillment with API](/use-cases/fulfillment-with-api): Learn how to integrate and use our API for seamless fulfillment processes.
* [Fulfillment with Self-Checkout](/use-cases/fulfillment-with-self-checkout): Discover how to use our self-checkout options for a smooth and efficient user experience.
* [Webhooks](/use-cases/webhooks): Learn what webhooks are and how to use them with our API
* [Webhooks API reference](/use-cases/webhooks-api-reference): Discover some examples on how to use our Webhooks API
***
### description: Guides to integrate SQUAKE's carbon APIs.
## Overview
In addition to our guides and documentation, we also offer a dedicated support page to assist you with any questions or issues you may encounter. Visit our [Support Page](https://support.squake.earth/) for detailed help, troubleshooting, and additional resources to get the most out of SQUAKE's services.
### :envelope\_with\_arrow: Contact Forms
Our contact forms are designed to help you communicate with us effectively. Whether you have feedback to share or need to report an incident, we've got you covered. Please use the appropriate form below:
* :envelope: [Contact Form](/feedback-form): Share your thoughts and suggestions about our services and processes, as well as get in contact with us.
* :warning: [Incident Form](/incident-form): Report any issues or incidents you've encountered, and our support team will respond as soon as possible.
### :file\_cabinet: API Requests & Responses
Our APIs are designed to be user-friendly and efficient, enabling smooth integration into your system. This section provides detailed documentation on how to make requests to our API, interpret responses, and handle data effectively. Whether you're just getting started or looking to optimize your usage, you'll find everything you need to successfully interact with our APIs.
### :new: Notable Changes
We continuously work to improve our services, and all notable updates and changes are documented in this section. Stay informed by reviewing the latest modifications to our offerings, including updates for accommodations, trains, flights, and environmental initiatives.
### :bulb: Use Cases
To help you get the most out of our services, we have documented various use cases that showcase how to utilize our offerings effectively:
* [Fulfillment with API](/use-cases/fulfillment-with-api): Learn how to integrate and use our API for seamless fulfillment processes.
* [Fulfillment with Self-Checkout](/use-cases/fulfillment-with-self-checkout): Discover how to use our self-checkout options for a smooth and efficient user experience.
* [Webhooks](/use-cases/webhooks): Learn what webhooks are and how to use them with our API
* [Webhooks API reference](/use-cases/webhooks-api-reference): Discover some examples on how to use our Webhooks API
### :detective: Audits
Our Audit Logs provides transparency by allowing authenticated clients to retrieve logs for carbon calculation requests when audit logging is enabled. These logs include details such as calculation inputs, results, and methodology references:
* [Retrieve the list of Audit logs](/audits/list-audit-logs): Retrieve a complete list of audit logs for your authenticated account.
* [Retrieve a specific Audit log](/audits/specific-audit-log): Retrieve detailed information about a specific audit log entry using its unique identifier.
### :technologist: Migration Guide
If you're transitioning from an older version of our services, our migration guide is here to help. Follow the detailed steps outlined in the guide to ensure a smooth transition:
* [From v1 to v2](/migration-guide/from-v1-to-v2): A comprehensive guide to migrating from version 1 to version 2, covering all necessary steps and considerations.
### :question: Sustainability FAQs
Our sustainability FAQ section explains key terms, frameworks, and concepts used throughout our documentation to support your understanding of emissions reporting and climate metrics in the travel and logistics sectors.
* [Sustainability FAQs](/faq): Browse frequently asked questions and educational explanations about CO2e, GWP, TTW/WTW, Scope 3.6, and more.
# Contact form
We value your opinion and would love to hear about your experience with us. Feel free to contact us, as your feedback is invaluable in helping us improve our services and processes.
Please take a moment to share your thoughts by using our [contact form](https://support.squake.earth/hc/en-gb/requests/new?ticket_form_id=5351278647581).
Thank you in advance for your time and insights!
# Incident form
If you've encountered an issue and need to report an incident, we're here to help. Please provide a detailed description of what went wrong, and our support team will get back to you as soon as possible.
To submit your report, simply use the following [incident form](https://support.squake.earth/hc/en-gb/requests/new?ticket_form_id=21154347283741).
We appreciate your cooperation and thank you in advance for helping us improve our services!
# Calculation API Examples
Understanding which API request items are required for each methodology can sometimes be confusing, as each activity and methodology has its unique parameters and considerations. To help guide you through this, we provide a clear breakdown, activity-by-activity and methodology-by-methodology, so you know exactly what data needs to be included in your request and what to expect in the response. This way, whether you're calculating emissions for a travel or logistics activity, you'll have a precise guide for crafting requests and interpreting responses for each specific case, ensuring accurate and reliable carbon calculations.
For **multi-leg passenger flights** sent as a single item with a **`routing`** chain (instead of origin and destination), see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing) under Travel.
# Travel
Traveling, whether for leisure, business, or necessity, plays a significant role in our daily lives. From flights and car rentals to accommodations, each step of a journey leaves an environmental footprint. With growing awareness of climate change, understanding and managing the carbon emissions associated with travel has become crucial. Whether you're planning a round-the-world trip or a simple weekend getaway, having insights into the emissions generated by each activity allows for better choices and a more sustainable approach to travel.
The SQUAKE platform offers the ability to calculate carbon emissions across various travel-related activities. These calculations provide transparency and foster sustainability by encouraging travelers to offset their emissions or choose greener alternatives. Whether you're flying internationally, renting a car, staying at a hotel, or taking a ferry, SQUAKE’s methodology helps in understanding the environmental impact of your journey.
### Perform a Calculation
`POST /v2/calculations`\
**Bearer auth required**
The `calculations` endpoint is used to calculate carbon emissions for one or multiple activities. For example, you can compute the carbon footprint of a journey consisting of a return flight, two cab rides, and a hotel stay, by passing all activities in the `items` array. By including the string literal `"items"` in the `"expand"` array, you can retrieve emissions for each item separately in addition to the total carbon quantity. For **multi-leg flight** items that use `routing` instead of `origin`/`destination`, you can also include **`"legs"`** in `expand` to receive per-leg emissions and distances on the flight item (see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing)).
This is a low-latency endpoint. Note that SQUAKE does not provide a unique identifier for any calculation results through this endpoint. You must quote a price on the pricing endpoint to purchase compensation for your carbon emissions.
Some data sets are extensive and are documented separately.
**Request Format** Content Type: `application/json`
#### Body
* **expand** `array[string]`\
If you include `"items"`, SQUAKE returns emissions per each item separately (in addition to a total value). You may pass **`"items"`** and **`"legs"`** together; `"legs"` adds per-leg breakdown for flight items that use **`routing`** (multi-leg itineraries). See [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).\
Values include: `"items"`, `"legs"` (use with routed flights when you need leg-level detail).
* **carbon\_unit** `string`\
SQUAKE uses The International System of Units (SI), commonly referred to as the "metric system".\
Possible Values: `"tonne"`, `"kilogram"`, or `"gram"`
* **distance\_unit** `string`\
SQUAKE uses common distance units.\
Possible Values: `"meter"`, `"kilometer"`, `"feet"`, `"mile"`, or `"nautical_mile"`\
Default value: `"kilometer"`
#### Generic API Request Sample
```json
{
"expand": [
"items"
],
"carbon_unit": "tonne",
"distance_unit": "kilometer",
"items": [
{
"type": "car",
"methodology": "ACRISS",
"external_reference": "Taxi",
"origin": "Alexanderplatz, Berlin, Germany",
"destination": "Berlin Brandenburg Airport, Schönefeld, Brandenburg, Germany",
"fuel_type": "diesel",
"acriss_car_type": "C"
},
{
"type": "flight",
"methodology": "TIM",
"origin": "BER",
"destination": "LHR",
"number_of_travelers": 1,
"booking_class": "business",
"airline": "BA",
"flight_number": "BA995",
"external_reference": "Flight"
},
{
"type": "car",
"methodology": "ACRISS",
"external_reference": "Taxi",
"origin": "Hounslow TW6 1QG, United Kingdom",
"destination": "150 Piccadilly, St. James's, London W1J 9BR, United Kingdom",
"fuel_type": "petrol",
"acriss_car_type": "S"
},
{
"type": "hotel",
"methodology": "HCMI",
"external_reference": "Hotel",
"country": "GB",
"city": "London",
"stars": 5,
"hcmi_member": false,
"number_of_nights": 3
},
{
"type": "car",
"methodology": "ACRISS",
"external_reference": "Taxi",
"origin": "150 Piccadilly, St. James's, London W1J 9BR, United Kingdom",
"destination": "Horley, Gatwick RH6 0NP, United Kingdom",
"fuel_type": "hev",
"acriss_car_type": "D"
},
{
"type": "flight",
"methodology": "TIM",
"origin": "LGW",
"destination": "BER",
"number_of_travelers": 1,
"booking_class": "business",
"airline": "U2",
"flight_number": "U28629",
"external_reference": "Flight"
},
{
"type": "car",
"methodology": "ACRISS",
"external_reference": "Taxi",
"origin": "Berlin Brandenburg Airport, Schönefeld, Brandenburg, Germany",
"destination": "Alexanderplatz, Berlin, Germany",
"fuel_type": "EV",
"acriss_car_type": "G"
}
]
}
```
#### Generic API Response Sample
```json
{
"carbon_quantity": 0.525911,
"carbon_unit": "tonne",
"items": [
{
"carbon_quantity": 0.002928,
"carbon_unit": "tonne",
"external_reference": "Taxi",
"type": "car",
"methodology": "ACRISS",
"distance": 24.0,
"distance_unit": "kilometer"
},
{
"carbon_quantity": 0.181885,
"carbon_unit": "tonne",
"external_reference": "Flight",
"type": "flight",
"methodology": "TIM",
"distance": 1065.0,
"distance_unit": "kilometer"
},
{
"carbon_quantity": 0.004396,
"carbon_unit": "tonne",
"external_reference": "Taxi",
"type": "car",
"methodology": "ACRISS",
"distance": 28.0,
"distance_unit": "kilometer"
},
{
"carbon_quantity": 0.175022,
"carbon_unit": "tonne",
"external_reference": "Hotel",
"type": "hotel",
"methodology": "HCMI"
},
{
"carbon_quantity": 0.005292,
"carbon_unit": "tonne",
"external_reference": "Taxi",
"type": "car",
"methodology": "ACRISS",
"distance": 49.0,
"distance_unit": "kilometer"
},
{
"carbon_quantity": 0.156388,
"carbon_unit": "tonne",
"external_reference": "Flight",
"type": "flight",
"methodology": "TIM",
"distance": 1054.0,
"distance_unit": "kilometer"
},
{
"carbon_quantity": 0.0,
"carbon_unit": "tonne",
"external_reference": "Taxi",
"type": "car",
"methodology": "ACRISS",
"distance": 24.0,
"distance_unit": "kilometer"
}
]
}
```
# Accommodation
The vacation rental industry, spanning city apartments to secluded cabins, contributes notably to tourism's carbon emissions. From daily energy use to guest transportation, every aspect leaves an environmental footprint. As sustainability awareness rises, travelers increasingly seek rentals that transparently disclose and compensate for their emissions.
SQUAKE offers the perfect solution for this sector. By utilizing SQUAKE's precise carbon calculation tools, rental platforms can accurately convey the emissions of each stay. Moreover, with SQUAKE's automated compensation mechanisms, guests can directly contribute to sustainability initiatives. Thus, the sector not only caters to eco-conscious travelers but also actively promotes a sustainable future.
# Accommodation: SQUAKE
:bulb: **High-Level Description**
The vacation rental industry has grown exponentially, presenting both opportunities and challenges when considering environmental impact. Recognizing the sector's potential to influence carbon emissions, SQUAKE developed a dedicated methodology tailored to vacation rentals. Rooted in comprehensive research and in-depth data analysis, SQUAKE's approach delves deep into the heating, electricity and water consumption, as well as into amenities.
The methodology is certified by **GUTcert** following the “**GHG Protocol - Product Life Cycle Accounting & Reporting Standard**”. By examining these varied elements, SQUAKE's methodology offers a holistic perspective on the climate impact of vacation rentals. The resulting metrics provide property owners and guests with insights, encouraging sustainable practices.
### Equation
```basic
co2_in_g =
number_of_nights * (square_meters * co2_for_heating_per_day_per_sqm_in_g
+ number_of_visitors * (co2_for_electricity_per_day_per_person_in_g + co2_for_water_per_day_per_person_in_g)
+ co2_for_sauna_per_day_in_g [only if true]
+ co2_for_swimming_pool_per_day_in_g [only if true]
+ co2_for_air_conditioner_per_day_in_g [only if true]
)
```
Calculation background
1. Carbon emissions per person is estimated from the following factors:
2. Carbon emissions per square meter:
3. average heat consumption a day, converted to carbon emissions a day (sources: Average CO2 emission factor (n.d.). Enerdata.; Common Carbon Metric (2009). UNEP-SBCI.; CO2 emissions per m2 for space heating (2011, August 8). European Environment Agency.; Dorothy L.Robinson. (2011, July). Australian wood heaters currently increase global warming and health costs. Atmospheric Pollution Research, Volume 2, Issue 3, July 2011, Pages 267-274.)
4. Carbon emissions for additional factors:
5. Seasoning logic:
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"external_reference": "test_1",
"type": "accommodation",
"number_of_nights": 10,
"starts_on": "2023-10-10",
"ends_on": "2023-10-21",
"sauna": false,
"country": "DE",
"number_of_travelers": 2,
"square_meters": 60,
"parking": true,
"garage": false,
"swimming_pool": false,
"air_conditioner": true,
"methodology": "SQUAKE"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"external_reference": "test_1",
"type": "accommodation",
"number_of_nights": 10,
"starts_on": "2023-10-10",
"ends_on": "2023-10-21",
"sauna": false,
"country": "DE",
"number_of_travelers": 2,
"square_meters": 60,
"parking": true,
"garage": false,
"swimming_pool": false,
"air_conditioner": true,
"methodology": "SQUAKE"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### **API Request Items**
* `"type"`: `"accommodation"` (required)
* `"methodology"`: `"SQUAKE"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"number_of_nights"`: Required if start and end dates are omitted; else this is ignored. Minimum value is `1`.
* `"starts_on"`: The format is ISO 8601 Date, `YYYY-MM-DD`. Required if season-specific methodology shall be used, or number of nights is omitted.
* `"ends_on"`: The format is ISO 8601 Date, `YYYY-MM-DD`. Required if season-specific methodology shall be used, or number of nights is omitted.
* `"country"`: Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively. Minimum length is `2`, maximum length is `3`. Format should match the following pattern: `^[A-Z]{2,3}$`.
* `"square_meters"`: The default value depends on the country. Minimum value is `1`.
* `"sauna"`: Default value is `false`.
* `"parking"`: Default value is `true`.
* `"swimming_pool"`: Default value is `false`.
* `"air_conditioner"`: Default value is `false`.
* `"garage"`: Default value is `false`.
* **Default values**
* `"sauna": false`
* `"swimming_pool": false`
* `"air_conditioner": false`
### Sample API Response
```json
{
"carbon_quantity": 248687,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 248687,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "accommodation",
"methodology": "SQUAKE"
}
]
}
```
### **Bibliography**
* Andrzejewski, M., et al. (2021, September 1). Analysis of pollutant emissions and fuel consumption for the use of a multi-storey car park. Combustion Engines, 187(4), 46-51. [DOI: https://doi.org/10.19206/CE-141740](https://doi.org/10.19206/CE-141740)
* Average CO2 emission factor (n.d.). Enerdata. Retrieved from
* Carbon intensity of electricity (n.d.). Our World in Data. Retrieved from
* Charting the Progress of Populations (n.d.). The United Nations. Retrieved from
* Common Carbon Metric (2009). UNEP-SBCI. Retrieved from
* CO2 intensity (n.d.) The World Bank. Retrieved from
* CO2 emissions per m2 for space heating (2011, August 8). European Environment Agency. Retrieved from
* Databank (n.d.) The World Bank. Retrieved from
* Dean, B., et al. (2018, May). The Future of Cooling: Opportunities for energy-efficient air conditioning. *International Energy Agency.* Retrieved from
* Dorothy L.Robinson. (2011, July). Australian wood heaters currently increase global warming and health costs. Atmospheric Pollution Research, Volume 2, Issue 3, July 2011, Pages 267-274. [doi.org/10.5094/APR.2011.033](https://doi.org/10.5094/APR.2011.033)
* Electric power consumption (2014). The World Bank. Retrieved from
* Gallion, T., et al. (2014, May 23). Estimating Water, Energy, and Carbon Footprints of Residential Swimming Pools. Water Reclamation and Sustainability, 343-359.
* Global Water Use (n.d.). Worldometer. Retrieved from
* Green Facts (n.d.). University of Michigan. Retrieved from
* Greenhouse gas emission intensity of electricity (2022, July 14). European Environment Agency. Retrieved from
* Greenhouse gas emissions by source sector (2022, June 10). eurostat. Retrieved from
* Guide to Low Carbon Swimming Pools (n.d.). Environmental Protection Department. Retrieved from
* Heckman L. (2009, September 10). Can lifts be energy-efficient, or should I take the stairs? *The Guardian.* Retrieved from
* How much power does a computer use? And how much CO2 does that represent? (2022) [energide.be](http://energide.be). Retrieved from [https://www.energuide.be/en/questions-answers/how-much-power-does-a-computer-use-and-how-much-co2-does-that-represent/54/#:\~:text=The power consumption of a,of CO2 per year](https://www.energuide.be/en/questions-answers/how-much-power-does-a-computer-use-and-how-much-co2-does-that-represent/54/#:~:text=The%20power%20consumption%20of%20a,of%20CO2%20per%20year).
* Jordaan, N., Narayanan, R. (2019, March 12). A numerical study on various heating options applied to swimming pool for energy saving. Energy Procedia, 160, 131-138.
* Juhrich, K. (2016, June 28). Co2 Emission Factors for Fossil Fuels. German Environment Agency. Retrieved from
* Kaza, S., et al. (2018). What a Waste 2.0: A Global Snapshot of Solid Waste Management to 2050. *World Bank Group*. Retrieved from
* Knago-Reynoso, M., et al. (2018, February 9). Estimation of Co2 emissions produced by commercial grills in Veracruz, Mexico. *Sustainability*, \*10...
# Bus
The bus travel sector, pivotal for mass transit, produces significant carbon emissions, primarily from fuel consumption and the lifecycle of the buses themselves. Despite being a greener alternative to individual car transport, there's an increasing emphasis on making bus travel even more sustainable, considering its ubiquity in urban and intercity transport.
SQUAKE's advanced system caters to this sector, offering precise carbon calculations for every bus journey. Transportation agencies and bus companies can utilize SQUAKE to quantify their carbon impact and identify areas for improvement. By adopting SQUAKE's solutions, the bus travel industry can progress towards a more eco-conscious future, benefiting both the environment and the millions relying on it daily.
# Bus: SQUAKE
💡 **High-Level Description:**
SQUAKE, a holistic and modern approach to carbon calculation, sets itself apart by its capacity to integrate operator-specific data within its methodology for the bus sector. Recognizing that buses, as a mode of public transport, can vary significantly in their environmental impact depending on numerous variables, the methodology's flexibility is its strength. Factors such as bus age, fuel type, maintenance schedules, route frequencies, and driver habits can all play crucial roles in determining the carbon footprint of a single bus journey.
With its roots in contemporary data analytics, SQUAKE not only aggregates broad industry metrics but also narrows down to the intricacies of individual bus operators. This ability to granulate allows transportation authorities and companies to gain precise insights and implement targeted strategies for carbon reduction. Such precision, driven by operator-specific data, translates into actionable solutions that make bus transportation greener and more sustainable.
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "bus",
"external_reference": "test_1",
"origin": "Berlin",
"destination": "Frankfurt am Main",
"number_of_travelers": 1,
"methodology": "SQUAKE",
"fuel_type": "diesel",
"operator_name": "flixbus"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "bus",
"external_reference": "test_1",
"origin": "Berlin",
"destination": "Frankfurt am Main",
"number_of_travelers": 1,
"methodology": "SQUAKE",
"fuel_type": "diesel",
"operator_name": "flixbus"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### **API Request Items**
* `"type"`: `"bus"` (required)
* `"methodology"`: `"SQUAKE"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"origin"`: SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"fuel_type"`: Values are `lng`, `diesel`, `lpg`, `phev`, `hydrogen`, `electricity`; defaults to `average`.
* `"operator_name"`: SQUAKE's methodology allows passing the operator's name to obtain a more accurate result. You can find the list of [supported operators here](https://squake.notion.site/31f83752e3bd4cf2ba314ceb8fa2acc6?v=5190873dd753431187b735a8fe40038f).
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
* **Default Values**
* `"fuel_type": "average"`
***
## Origin/Destination Formats (Enriched)
SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:
* **Addresses:** Use the *Post* standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `"MUC"`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
**Provider/Stop Codes for Buses**
* You can also reference **bus stops or stations** using provider-prefixed stop IDs:
* Format: `:` (e.g., `flixbus:2006`)
* **Common provider prefixes:**
* `flixbus`
* `distribusion`
* `busbud`
> If a value cannot be resolved, SQUAKE will **fallback to generic (non-journey-specific)** bus factors under the SQUAKE methodology.
**Examples**
```jsonc
// Using provider stop codes
{
"type": "bus",
"methodology": "SQUAKE",
"origin": "flixbus:berlin_zob",
"destination": "flixbus:frankfurt_sued",
"operator_name": "flixbus",
"number_of_travelers": 1
}
// Using UN/LOCODEs (for multimodal contexts)
{
"type": "bus",
"methodology": "SQUAKE",
"origin": "DEBER",
"destination": "DEFRA",
"number_of_travelers": 1
}
// Using coordinates
{
"type": "bus",
"methodology": "SQUAKE",
"origin": "+52.501,13.281",
"destination": "+50.094,8.662",
"number_of_travelers": 1
}
```
***
### **Sample API Response**
```json
{
"carbon_quantity": 12374,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 12374,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "bus",
"methodology": "SQUAKE",
"distance": 538.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* Chang, Ching-Chih, et al. “Life Cycle Assessment of Carbon Footprint in Public Transportation - a Case Study of Bus Route NO. 2 in Tainan City, Taiwan.” *Procedia Manufacturing*, vol. 30, Elsevier BV, 2019, pp. 388–95. .
* Logan, Kathryn G., et al. “Electric and Hydrogen Buses: Shifting From Conventionally Fuelled Cars in the UK.” *Transportation Research Part D: Transport and Environment*, vol. 85, Elsevier BV, Aug. 2020, p. 102350. .
* "Which form of transport has the smallest carbon footprint?" *Our World in Data*, ourworldindata.org/travel-carbon-footprint.
# Bus: DEFRA 🇬🇧
💡 **High-Level Description:**
DEFRA's methodology for calculating the carbon footprint of bus travel is based on standardized emission factors published by the UK government. These factors are derived from extensive national data sources and provide a reliable basis for estimating greenhouse gas emissions from different types of bus transportation.
DEFRA's methodology takes into account various bus categories, including local buses operating within and outside London, as well as long-distance coaches. Emissions are calculated based on factors such as fuel consumption, average occupancy rates, and energy efficiency. Additionally, DEFRA offers flexibility in emissions reporting by supporting two energy scopes: **Tank-to-Wheel (TTW)** and **Well-to-Wheel (WTW)**, with WTW being the default option for a more comprehensive lifecycle assessment.
By leveraging DEFRA's well-established reporting framework, businesses and policymakers can ensure consistent and transparent carbon accounting for bus travel, aligning with UK environmental reporting regulations and sustainability strategies. **Versioning:** Use `methodology_version` to pin the DEFRA **Conversion Factors** year (e.g., "2024"). If omitted, SQUAKE **uses the latest supported year**.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "bus",
"external_reference": "test_1",
"origin": "London",
"destination": "Bristol",
"bus_type": "coach",
"number_of_travelers": 3,
"energy_scope": "wtw",
"methodology": "DEFRA",
"methodology_version": "2024"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "bus",
"external_reference": "test_1",
"origin": "London",
"destination": "Bristol",
"bus_type": "coach",
"number_of_travelers": 3,
"energy_scope": "wtw",
"methodology": "DEFRA",
"methodology_version": "2024"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### **API Request Items**
* `type`: `bus` **(required)**
* `methodology`: `DEFRA` **(required)**
* `methodology_version`: DEFRA Conversion Factors year (e.g., `2024`). **Optional**; if omitted → **latest supported year**.
* `external_reference`: Correlate response to request (max 128 chars).
* `number_of_travelers`: Minimum `1`. **Default:** `1`.
* `origin` / `destination`: Postal, IATA/ICAO, UN/LOCODE, or `lat,lon`.
* `distance_in_km`: If present, **overrides** origin/destination.
* `bus_type` (options):
* `local_bus_not_london`
* `local_bus_london`
* `average_local_bus` *(default)*
* `coach`
* `energy_scope`:
* `wtw` *(default)* — well‑to‑wheel
* `ttw` — tank‑to‑wheel
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
## Origin/Destination Formats (Enriched)
SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:
* **Addresses:** Use the Post standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `MUC`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `DEHAM`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `+40.712,-74.006`).
**Provider/Stop Codes for Buses**
* You can also reference **bus stops or stations** using provider-prefixed stop IDs:
* Format: `:` (e.g., `flixbus:2006`).
* **Common provider prefixes:** `flixbus`, `distribusion`, `busbud`.
> If a value cannot be resolved, SQUAKE will **fallback to generic (non‑journey‑specific)** DEFRA bus factors.
**Examples**
```jsonc
// Using provider stop codes
{
"type": "bus",
"methodology": "DEFRA",
"origin": "flixbus:london_victoria",
"destination": "flixbus:bristol_bond_st",
"bus_type": "coach",
"number_of_travelers": 1,
"energy_scope": "wtw",
"methodology_version": "2024"
}
// Using UN/LOCODEs
{
"type": "bus",
"methodology": "DEFRA",
"origin": "GBLON",
"destination": "GBBRS",
"bus_type": "coach",
"number_of_travelers": 1
}
// Using coordinates
{
"type": "bus",
"methodology": "DEFRA",
"origin": "+51.495,-0.144",
"destination": "+51.455,-2.597",
"bus_type": "coach",
"number_of_travelers": 1
}
```
***
### **Default Values**
* `bus_type`: `average_local_bus`
* `energy_scope`: `wtw`
* `methodology_version`: latest supported DEFRA year
***
### **Sample API Response**
```json
{
"carbon_quantity": 15240,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 15240,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "bus",
"methodology": "DEFRA",
"methodology_version": "2024",
"bus_type": "coach",
"energy_scope": "wtw",
"distance": 190.0,
"distance_unit": "kilometer"
}
]
}
```
***
### **Versions**
* **Behavior:** If `methodology_version` is omitted, SQUAKE automatically applies the **latest supported** DEFRA Conversion Factors year. Pin a specific year for reproducibility and auditability.
***
### **Bibliography**
* UK Government — **Greenhouse Gas Emissions: Research & Statistics**:
# Car
Cars, the linchpins of modern transportation, bring with them a hefty carbon trail. From manufacture to daily operations and finally disposal, every car contributes significantly to global emissions. These climate impacts differ based on fuel type, efficiency, and car model, requiring intricate calculations to determine each vehicle's exact environmental toll.
SQUAKE steps in as the ideal solution. Tailored for the complexities of car emissions, it delivers precise calculations for varied vehicle types and usage patterns. This empowers manufacturers, service providers, and individuals to make informed decisions, driving towards greener options. With SQUAKE, the road to sustainable car travel is clearer than ever.
# Car: ACRISS
:bulb: **High‑Level Description**
* **ACRISS** (Association of Car Rental Industry Systems Standards) is known for its rental car coding standards and, increasingly, for methodologies addressing environmental impacts in automotive travel.
* The **ACRISS car methodology** differentiates emissions by **vehicle class**, **fuel/energy type**, and **usage patterns** (e.g., distance, trip context), acknowledging that a compact city car differs markedly from a large SUV.
* It incorporates **vehicle specifications**, **driving behavior assumptions**, and **maintenance practices** to estimate carbon emissions.
* The approach reflects the market shift toward **EVs, HEVs, and PHEVs**, and is **updated periodically** to remain aligned with industry standards and technology advances.
***
## Sample API Requests
### A. Route-based request without audit mode (origin/destination or explicit distance)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"methodology": "ACRISS",
"external_reference": "string",
"origin": "Frankfurt am Main, Germany",
"destination": "Berlin, Germany",
"fuel_type": "diesel",
"acriss_car_type": "C"
}
]
}
```
### B. Route-based request with audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "car",
"methodology": "ACRISS",
"external_reference": "string",
"origin": "Frankfurt am Main, Germany",
"destination": "Berlin, Germany",
"fuel_type": "diesel",
"acriss_car_type": "C"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### C. Duration-based request (fallback when distance is unknown)
> When the trip distance is unknown, you may pass `number_of_days`. The API will estimate the distance as\
> `estimated_distance_in_km = number_of_days * 60`.
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"methodology": "ACRISS",
"external_reference": "string",
"fuel_type": "diesel",
"acriss_car_type": "C",
"number_of_days": 5
}
]
}
```
> **Precedence rule:** If `distance_in_km` is provided, it will be used and **takes priority** over both `origin`/`destination` and `number_of_days`.
***
## Sample API Response
```json
{
"carbon_quantity": 65636,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 65636,
"carbon_unit": "gram",
"external_reference": "string",
"type": "car",
"methodology": "ACRISS",
"distance": 538.0,
"distance_unit": "kilometer"
}
]
}
```
***
## API Request Items
* `"type"`: `"car"` (**required**).
* `"methodology"`: `"ACRISS"` (**required**).
* `"external_reference"`: A unique identifier (max 128 chars) to link the result to your item (useful for multi-item requests where order is not guaranteed).
* `"origin"`: SQUAKE will try to resolve `origin`/`destination` regardless of format. Prefer:
* **Addresses**: postal standard.
* **Airports**: IATA/ICAO `^[A-Z]{3,4}$` (e.g., `"MUC"`).
* **Trade/transport locations**: UN/LOCODE `^[A-Z]{2}\W?[A-Z2-9]{3}$` (e.g., `"DEHAM"`).
* **Coordinates**: `^[-+]?\\d{1,3}\\.\\d{1,10}\\s?,\\s?[-+]?\\d{1,3}\\.\\d{1,10}$` (e.g., `"+40.712,-74.006"`).
* `"destination"`: Same formats and rules as `"origin"`.
* `"distance_in_km"`: If present, **takes priority** over `origin`/`destination` and `number_of_days`. If both `distance_in_km` and `origin`/`destination` are provided, `distance_in_km` is used.
* `"number_of_days"`: **integer** (display name: **Number‑Of‑Days**), **>= 1**.
* Use when trip distance is **unknown**.
* The API estimates distance as: `estimated_distance_in_km = number_of_days * 60`.
* **Precedence:** `distance_in_km` > `origin/destination` > `number_of_days` (fallback).
* `"fuel_type"`: One of `petrol`, `diesel`, `hev`, `phev`, `electricity`. Default for ACRISS is `petrol`.
* `"acriss_car_type"`: Car classes:\
`C` (Compact), `D` (Compact Elite), `E` (Economy), `F` (Fullsize), `G` (Fullsize Elite), `H` (Economy Elite), `I` (Intermediate), `J` (Intermediate Elite), `L` (Luxury), `M` (Mini), `N` (Mini Elite), `P` (Premium), `R` (Standard Elite), `S` (Standard), `U` (Premium Elite), `W` (Luxury Elite), `X` (Special). Default: `E`.
* `"sipp_car_type"`: If `acriss_car_type` is not passed, SQUAKE will auto‑resolve using the **SIPP code**. **Mutually exclusive** with `pseudo_car_type` (provide only one).
* `"pseudo_car_type"`: If neither `acriss_car_type` nor `sipp_car_type` are passed, SQUAKE will auto‑resolve using **Pseudo code**. **Mutually exclusive** with `sipp_car_type`. Allowed values:\
`ACAR`, `ACGO`, `ACNV`, `ACPG`, `ACPR`, `ACRS`, `ADSL`, `AEIG`, `AELC`, `AELT`, `AETH`, `AFWD`, `AGRN`, `AHYB`, `AHYD`, `ALLB`, `ALLC`, `ALLD`, `ALMO`, `AMAN`, `AMCY`, `AMFP`, `AMNO`, `AMTO`, `ANIN`, `AOFR`, `APET`, `APUP`, `AREC`, `ASEV`, `ASIX`, `ASPC`, `ASPT`, `ASUV`, `ATRV`, `AUTO`, `AVAN`, `AWGN`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
## Default Values
* `"fuel_type": "petrol"`
* `"acriss_car_type": "E"`
***
## Notes
* **Data quality tip:** whenever possible, pass the actual `distance_in_km`—it yields the most accurate result. `number_of_days` is a convenience fallback and a coarse approximation.
* If neither `distance_in_km` nor `origin`/`destination` are supplied, the API will use `number_of_days` (if provided) to estimate distance; otherwise the request may be insufficient to compute trip emissions.
***
## Bibliography
* Environmental Responsibility & CO2 Emissions Guidelines (n.d.). **ACRISS**. Retrieved from
# Car: BASIC
:bulb: **High-Level Description**
The **BASIC** methodology is a transparent, input-driven calculator for car travel when you already know either:
* the **specific emission rate** of the vehicle in **gCO₂/km**, **or**
* the **energy/fuel consumption** (e.g., L/100 km, kWh/100 km) **plus** the **fuel type** (to derive gCO₂/km via fuel-specific factors).
It is designed for simple, traceable calculations where the data source is your own measurement, OEM specs, or a trusted dataset. BASIC does **not** infer vehicle classes or default factors; it relies on **your supplied intensity** (g/km) or **your supplied consumption** with **explicit fuel type**.
**Audit mode:** Set `items[].audit = true` to create immutable audit records (must be enabled for your account).
***
## Sample API Requests
### A. Direct intensity (preferred when you know gCO₂/km)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"methodology": "BASIC",
"external_reference": "TRIP-001",
"distance_in_km": 245.6,
"co2_grams_per_km": 120
}
]
}
```
### B. Consumption-based (derive g/km from 100-km consumption + fuel type)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"methodology": "BASIC",
"external_reference": "TRIP-002",
"origin": "Munich, Germany",
"destination": "Prague, Czechia",
"consumption_per_100_km": 6.2,
"fuel_type": "petrol"
}
]
}
```
### C. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "car",
"methodology": "BASIC",
"external_reference": "TRIP-004",
"distance_in_km": 245.6,
"co2_grams_per_km": 120
}
]
}
```
### D. Duration-based distance fallback (when distance is unknown)
> If you don’t have distance or origin/destination, you may pass `number_of_days`.\
> SQUAKE estimates: `estimated_distance_in_km = number_of_days * 60`.
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"methodology": "BASIC",
"external_reference": "TRIP-003",
"number_of_days": 4,
"co2_grams_per_km": 95
}
]
}
```
> **Precedence rules**\
> **Distance source:** `distance_in_km` > `origin/destination` > `number_of_days`.\
> **Intensity source:** `co2_grams_per_km` > (`consumption_per_100_km` + `fuel_type`).\
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
## Sample API Response
```json
{
"carbon_quantity": 29472,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 29472,
"carbon_unit": "gram",
"external_reference": "TRIP-001",
"type": "car",
"methodology": "BASIC",
"distance": 245.6,
"distance_unit": "kilometer"
}
]
}
```
***
## API Request Items
* `"type"`: `"car"` **(required)**
* `"methodology"`: `"BASIC"` **(required)**
* `"external_reference"`: Optional correlation ID (≤128 chars)
* **Distance inputs (choose one):**
* `"distance_in_km"`: numeric (overrides other distance inputs)
* `"origin"` **and** `"destination"`: postal text, UN/LOCODE, IATA/ICAO, or `"lat,lon"`
* `"number_of_days"`: integer ≥ 1 (fallback; estimates distance as `days * 60`)
* **Intensity inputs (choose one path):**
* `"co2_grams_per_km"`: number ≥ 0 **(direct gCO₂/km)**
* **OR** `"consumption_per_100_km"` **and** `"fuel_type"`:
* `"consumption_per_100_km"`: number \[0..1000]
* `"fuel_type"`: one of\
`"diesel" | "petrol" | "electricity" | "ethanol" | "bio_diesel" | "lpg" | "hydrogen" | "hvo"`
* `"audit"`: boolean (immutable audit record; feature-gated)
> **Validation tip:** For the **consumption** path, `fuel_type` is **mandatory**. For the **g/km** path, `fuel_type` is **not required**.
***
## Default Values
* No default for `"fuel_type"` (required **only** when using `"consumption_per_100_km"`).
* No default for `"co2_grams_per_km"` or `"consumption_per_100_km"`—you must provide **one** of the intensity paths.
* Distance estimation default for `"number_of_days"`: **60 km/day**.
***
## Notes
* Use **direct `co2_grams_per_km`** whenever available (OEM/telematics/lab data) for maximum fidelity.
* When using **consumption**, ensure the unit matches what your integration expects (e.g., **L/100 km** for liquid fuels, **kWh/100 km** for BEVs).
* BASIC does **not** infer vehicle classes or apply regional defaults; it uses exactly what you supply.
* For electric vehicles, either provide **`co2_grams_per_km`** (preferred if you have grid-mix allocation) or **`consumption_per_100_km`** with `"fuel_type": "electricity"` (uses configured electricity factors).
***
## Bibliography
* **Smart Freight Centre (SFC)** — *Global Logistics Emissions Council (GLEC) Framework for Logistics Emissions Accounting*, latest edition.
* **SFC** — *GLEC Framework Guidance & Technical Documentation* (supporting fuel/energy factors and calculation principles).
# Car: DEFRA 🇬🇧
:bulb: **High-Level Description**
The Department for Environment, Food & Rural Affairs (DEFRA) of the UK has been a stalwart in environmental governance and establishing methodologies across various sectors. Within the car sector, DEFRA's methodology focuses keenly on providing robust and comprehensible metrics for carbon emissions. Recognizing the massive contribution of vehicles to the UK's carbon footprint, DEFRA's guidelines are tailored to encompass the diverse range of vehicles on the roads, from compact cars to SUVs.
DEFRA's approach not only accounts for direct emissions derived from fuel combustion but also considers the broader life-cycle emissions of vehicles, including manufacturing, maintenance, and disposal. Their methodology, backed by extensive research and consultation with automotive industry experts, provides a solid foundation for the UK's policy-making, encouraging sustainable car manufacturing and usage. Through DEFRA's efforts, consumers, manufacturers, and policymakers are better equipped to make environmentally conscious decisions regarding transportation.
**Versioning:** Use `methodology_version` to pin a specific **Conversion Factors** year (e.g., `"2024"`). If omitted, SQUAKE **uses the latest supported year**.
***
## Sample API Requests
### A. Route-based request without audit mode (origin/destination or explicit distance)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"methodology": "DEFRA",
"external_reference": "string",
"origin": "Frankfurt am Main, Germany",
"destination": "Berlin, Germany",
"fuel_type": "hev",
"car_type": "dual_purpose_4x4",
"energy_scope": "ttw",
"methodology_version": "2024"
}
]
}
```
### B. Route-based request with audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "car",
"methodology": "DEFRA",
"external_reference": "string",
"origin": "Frankfurt am Main, Germany",
"destination": "Berlin, Germany",
"fuel_type": "hev",
"car_type": "dual_purpose_4x4",
"energy_scope": "ttw",
"methodology_version": "2024"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### C. Duration-based request (fallback when distance is unknown)
> When the trip distance is unknown, you may pass `number_of_days`. The API will estimate the distance as\
> `estimated_distance_in_km = number_of_days * 60`.
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"methodology": "DEFRA",
"external_reference": "string",
"fuel_type": "hev",
"car_type": "dual_purpose_4x4",
"energy_scope": "ttw",
"methodology_version": "2024",
"number_of_days": 5
}
]
}
```
> **Precedence rule:** If `distance_in_km` is provided, it will be used and **takes priority** over both `origin`/`destination` and `number_of_days`.
***
## Sample API Response
```json
{
"carbon_quantity": 10764,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 10764,
"carbon_unit": "gram",
"external_reference": "string",
"type": "car",
"methodology": "DEFRA",
"methodology_version": "2024",
"distance": 110.0,
"distance_unit": "kilometer"
}
]
}
```
***
## API Request Items
* `"type"`: `"car"` **(required)**
* `"methodology"`: `"DEFRA"` **(required)**
* `"methodology_version"`: DEFRA **Conversion Factors** year (e.g., `"2024"`). **Optional**; if omitted → **latest supported year**.
* `"external_reference"`: Unique identifier to correlate responses (max 128 chars).
* `"origin"` / `"destination"`: Postal, IATA/ICAO, UN/LOCODE, or `"lat,lon"`; SQUAKE resolves distance.
* `"distance_in_km"`: If present, **overrides** origin/destination resolution and `number_of_days`.
* `"number_of_days"`: **integer** (display name: **Number-Of-Days**), **>= 1**.
* Use when trip distance is **unknown**.
* Estimated distance formula: `estimated_distance_in_km = number_of_days * 60`.
* **Precedence:** `distance_in_km` > `origin/destination` > `number_of_days` (fallback).
* `"fuel_type"`: `"petrol"`, `"diesel"`, `"hev"`, `"phev"`, `"electricity"`, `"average"` *(default: `"average"`)*.
* `"acriss_car_type"`: ACRISS segment letters (e.g., `C`,`D`,`E`,`F`,`G`,`H`,`I`,`J`,`L`,`M`,`N`,`P`,`R`,`S`,`U`,`W`,`X`). **Mutually exclusive** with `"car_type"`.
* `"sipp_car_type"`: If `acriss_car_type` not passed, can be used to infer class. **Mutually exclusive** with `"car_type"`.
* `"car_type"`: `"mini"`, `"supermini"`, `"lower_medium"`, `"upper_medium"`, `"executive"`, `"luxury"`, `"sports"`, `"dual_purpose_4x4"`, `"mpv"`, `"small"`, `"medium"`, `"large"`, `"average"` *(default: `"average"`)*.
* `"energy_scope"`: `"wtw"` *(default)* or `"ttw"`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
## Default Values
* `"fuel_type": "average"`
* `"car_type": "average"`
* `"energy_scope": "wtw"`
* `"methodology_version"`: **latest supported DEFRA year**
***
## Notes
* **Data quality tip:** whenever possible, pass the actual `distance_in_km`—it yields the most accurate result. `number_of_days` is a convenience fallback and a coarse approximation.
* Pin `methodology_version` for **reproducibility and auditability** in long-lived reports.
* If neither `distance_in_km` nor `origin`/`destination` are supplied, the API will use `number_of_days` (if provided) to estimate distance; otherwise the request may be insufficient to compute trip emissions.
***
## Bibliography
* UK Government — **Greenhouse gas emissions: Research & statistics**:
* Bramwell, R., et al. (2024). *Government Greenhouse Gas Conversion Factors for Company Reporting — Methodology*. (Methodology paper PDF).
# Car: EEA 🇪🇺
💡 **High-Level Description**
The European Environment Agency (EEA) stands as a major institution responsible for providing valuable insights into environmental concerns, including carbon emissions in various sectors. With the transportation sector being one of the chief contributors to greenhouse gas emissions, cars, in particular, have remained a significant focus for the EEA. To address the environmental concerns stemming from the car sector, the EEA has developed a methodology to ensure a standardized measurement and reporting mechanism for carbon emissions.
This methodology by the EEA aims to capture an all-encompassing view of the car sector, considering variables such as vehicle type, fuel consumption patterns, and the impact of innovative technologies. By implementing this methodology, the EEA aims to facilitate informed policy decisions at the European level and provide data that can foster sustainable advancements in the automotive industry.
***
## Sample API Requests
### A. Route-based request without audit mode (origin/destination or explicit distance)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"external_reference": "test_3",
"origin": "Menton, France",
"destination": "Paris, France",
"manufacturer": "VOLVO",
"model": "V40",
"model_year": 2017,
"fuel_type": "diesel",
"engine_capacity_in_cubic_cm": 1969,
"electric_energy_consumption_in_kw": 88,
"country": "PT",
"methodology": "EU-EEA"
}
]
}
```
### B. Route-based request with audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "car",
"external_reference": "test_3",
"origin": "Menton, France",
"destination": "Paris, France",
"manufacturer": "VOLVO",
"model": "V40",
"model_year": 2017,
"fuel_type": "diesel",
"engine_capacity_in_cubic_cm": 1969,
"electric_energy_consumption_in_kw": 88,
"country": "PT",
"methodology": "EU-EEA"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### C. Duration-based request (fallback when distance is unknown)
> When the trip distance is unknown, you may pass `number_of_days`. The API will estimate the distance as\
> `estimated_distance_in_km = number_of_days * 60`.
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"external_reference": "test_3",
"manufacturer": "VOLVO",
"model": "V40",
"model_year": 2017,
"fuel_type": "diesel",
"engine_capacity_in_cubic_cm": 1969,
"electric_energy_consumption_in_kw": 88,
"country": "PT",
"methodology": "EU-EEA",
"number_of_days": 5
}
]
}
```
> **Precedence rule:** If `distance_in_km` is provided, it will be used and **takes priority** over both `origin`/`destination` and `number_of_days`.
***
## Sample API Response
```json
{
"carbon_quantity": 213823,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 213823,
"carbon_unit": "gram",
"external_reference": "test_3",
"type": "car",
"methodology": "EU-EEA",
"distance": 876.0,
"distance_unit": "kilometer"
}
]
}
```
***
## API Request Items
* `"type"`: `"car"` (**required**)
* `"methodology"`: `"EU-EEA"` (**required**)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"number_of_days"`: **integer** (display name: **Number-Of-Days**), **>= 1**.
* Use when trip distance is **unknown**.
* Estimated distance formula: `estimated_distance_in_km = number_of_days * 60`.
* **Precedence:** `distance_in_km` > `origin/destination` > `number_of_days` (fallback).
* `"fuel_type"`: Values are `diesel`, `petrol`, `hybrid`, `electricity`, `midgrade_gasoline`, `natural_gas`, `premium_gasoline`, `regular_gasoline`, or `propane`.
* `"manufacturer"`: See the [database](https://squake.notion.site/Car-EU-EEA-ab71fdacedb64b5184a62761b29c15a4?pvs=4)
* `"model"`: See the [database](https://squake.notion.site/Car-EU-EEA-ab71fdacedb64b5184a62761b29c15a4?pvs=4)
* `"model_year"`: See the [database](https://squake.notion.site/Car-EU-EEA-ab71fdacedb64b5184a62761b29c15a4?pvs=4)
* `"country"`: Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively. Minimum length is `2`, maximum length is `3`. Format should match the following pattern: `^[A-Z]{2,3}$`.
* `"electric_energy_consumption_in_kw"`: See the [database](https://squake.notion.site/Car-EU-EEA-ab71fdacedb64b5184a62761b29c15a4?pvs=4)
* `"engine_capacity_in_cubic_cm"`: See the [database](https://squake.notion.site/Car-EU-EEA-ab71fdacedb64b5184a62761b29c15a4?pvs=4)
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### Default values
* `"fuel_type": "petrol"`
***
## Notes
* **Data quality tip:** whenever possible, pass the actual `distance_in_km`—it yields the most accurate result. `number_of_days` is a convenience fallback and a coarse approximation.
***
## Bibliography
* EEA, 2019, *Trends and projections in Europe 2019 — tracking progress towards Europe’s climate and energy targets*, EEA Report, 15/2019, European Environment Agency.
* EU, 2019, Regulation (EU) 2019/631 of the European Parliament and of the Council of 17 April 2019 setting CO2 emission performance standards for new passenger cars and for new light commercial vehicles, and repealing Regulations (EC) No 443/2009 and (EU) No 510/2011, OJ L 111, 25.4.2019, p. 13-53.
* *Monitoring of CO2 Emissions From Passenger Cars*. co2cars.apps.eea.europa.eu.
* *CO2 Performance of New Passenger Cars in Europe*. 26 Sept. 2022, [www.eea.europa.eu/ims/co2-performance-of-new-passenger](http://www.eea.europa.eu/ims/co2-performance-of-new-passenger).
# Car: EPA 🇺🇸
💡 **High-Level Description:**
The Environmental Protection Agency (EPA) of the United States has a long-standing tradition of overseeing and addressing the environmental impacts stemming from various industrial sectors. Within the realm of transportation, the car sector holds prominence due to its vast reach and consequential emissions. Recognizing the need to curb emissions from cars, the EPA devised a robust methodology to estimate and monitor CO₂ emissions from automotive sources.
EPA's approach to the car sector isn't just about numbers; it integrates a holistic view, considering elements such as vehicle design, fuel type, driving conditions, and technological innovations in emission control. The underlying goal is not only to measure but also to incentivize the adoption of cleaner and more efficient automotive technologies. By ensuring a precise evaluation of emissions, the EPA aims to influence policy and regulatory measures, promoting a sustainable transportation future for the country.
***
## Sample API Requests
### A. Route-based request without audit mode (origin/destination or explicit distance)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"external_reference": "test_3",
"origin": "Menton, France",
"destination": "Paris, France",
"manufacturer": "mercedes_benz",
"model": "500sel",
"model_year": 1985,
"fuel_type": "regular_gasoline",
"epa_vehicle_size_class": "midsize_cars",
"specific_transmission": "automatic_4_spd",
"engine_displacement_in_liters": 5.0,
"epa_model_type_index": 27914,
"engine_cylinders": 8,
"methodology": "US-EPA"
}
]
}
```
### B. Route-based request with audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "car",
"external_reference": "test_3",
"origin": "Menton, France",
"destination": "Paris, France",
"manufacturer": "mercedes_benz",
"model": "500sel",
"model_year": 1985,
"fuel_type": "regular_gasoline",
"epa_vehicle_size_class": "midsize_cars",
"specific_transmission": "automatic_4_spd",
"engine_displacement_in_liters": 5.0,
"epa_model_type_index": 27914,
"engine_cylinders": 8,
"methodology": "US-EPA"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### C. Duration-based request (fallback when distance is unknown)
> When the trip distance is unknown, you may pass `number_of_days`. The API will estimate the distance as\
> `estimated_distance_in_km = number_of_days * 60`.
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "car",
"external_reference": "test_3",
"manufacturer": "mercedes_benz",
"model": "500sel",
"model_year": 1985,
"fuel_type": "regular_gasoline",
"epa_vehicle_size_class": "midsize_cars",
"specific_transmission": "automatic_4_spd",
"engine_displacement_in_liters": 5.0,
"epa_model_type_index": 27914,
"engine_cylinders": 8,
"methodology": "US-EPA",
"number_of_days": 5
}
]
}
```
> **Precedence rule:** If `distance_in_km` is provided, it will be used and **takes priority** over both `origin`/`destination` and `number_of_days`.
***
## Sample API Response
```json
{
"carbon_quantity": 345527,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 345527,
"carbon_unit": "gram",
"external_reference": "test_3",
"type": "car",
"methodology": "US-EPA",
"distance": 876.0,
"distance_unit": "kilometer"
}
]
}
```
***
## API Request Items
* `"type"`: `"car"` (**required**)
* `"methodology"`: `"US-EPA"` (**required**)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\\d{1,3}\\.\\d{1,10}\\s?,\\s?[-+]?\\d{1,3}\\.\\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: Same formats and rules as `"origin"`.
* `"distance_in_km"`: If present, **overrides** origin/destination resolution and `number_of_days`.
* `"number_of_days"`: **integer** (display name: **Number-Of-Days**), **>= 1**.
* Use when trip distance is **unknown**.
* Estimated distance formula: `estimated_distance_in_km = number_of_days * 60`.
* **Precedence:** `distance_in_km` > `origin/destination` > `number_of_days` (fallback).
* `"fuel_type"`: One of `electricity`, `premium_gasoline`, `regular_gasoline`, `diesel`, `natural_gas`, `midgrade_gasoline`, or `propane`.
* `"manufacturer"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"model"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"model_year"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"country"`: Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively. Minimum length is `2`, maximum length is `3`. Format: `^[A-Z]{2,3}$`.
* `"electric_energy_consumption_in_kw"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"engine_capacity_in_cubic_cm"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"engine_cylinders"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"epa_model_type_index"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"engine_displacement_in_liters"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"specific_transmission"`: See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"epa_vehicle_size_class"`: EPA size class has a specific division of car sizes according to `US-EPA`. See the [database](https://squake.notion.site/863b63e1ae124f6e8fdf5cf09e96bd70?v=34c22d8966fa48fc80bb660e8c4fd6d7\&pvs=4)
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### Default values
* `"fuel_type": "regular_gasoline"`
***
## Notes
* **Data quality tip:** whenever possible, pass the actual `distance_in_km`—it yields the most accurate result. `number_of_days` is a convenience fallback and a coarse approximation.
***
## Bibliography
* FuelEconomy.gov Web Services (n.d.). FuelEconomy. Retrieved from
* Greenhouse Gas Emissions from a Typical Passenger Vehicle (n.d.). United States Environmental Protection Agency. Retrieved from vehicle#:\~:text=typical%20passenger%20vehicle%3F-,A%20typical%20passenger%20vehicle%20emits%20about%204.6%20metric%20tons%20of,around%2011%2C500%20miles%20per%20year
* Tiseo, I. (2021, December 14). Passenger car carbon dioxide emissions worldwide 2010-2020. Retrieved from
* Emission Factors for Greenhouse Gas Inventories (2025, Jan). EPA. Retrieved from
# Event
Events, be it corporate conferences, festivals, or private celebrations, accumulate significant carbon footprints from travel, accommodation, food, and electricity usage. Beyond just the attendees, the production and disposal of materials can also escalate emissions, underscoring the urgency for a more sustainable approach.
Through SQUAKE, event organizers can calculate the exact carbon footprint of their events, enabling them to make more eco-friendly choices. By understanding and addressing these emissions, every event has the potential to set a new benchmark for environmental responsibility.
# Event: HCMI & CHSB
💡 **High-Level Description**
The events sector, with its vast scope and massive carbon footprint, has long been under scrutiny for its environmental impact. Recognizing the urgency for sustainability in this industry, two methodologies—HCMI (Hotel Carbon Measurement Initiative) and CHSB (Cornell Hotel Sustainability Benchmark Index)—were introduced. Initially tailored for the hotel industry, these methodologies were soon recognized for their potential applicability in gauging sustainability within the broader events sector.
HCMI, developed in collaboration with leading hoteliers, offers a unified approach to measuring and communicating the carbon footprint of hotel stays and meetings. Given the close interrelation between hotel and event industries, it was a natural progression for event organizers to leverage HCMI's precise carbon measurement tools. On the other hand, CHSB, developed by Cornell University, serves as a benchmarking tool, allowing event managers to compare their sustainability performance against global standards. As more event planners prioritize eco-friendliness and sustainability, both HCMI and CHSB have emerged as indispensable tools, reshaping the event industry's sustainability landscape.
Hotel Carbon Measurement Initiative
Hotel Carbon Measurement Initiative (HCMI) is a free methodology and tool for hotels to calculate the carbon footprint of hotel stays and meetings in their properties.
The methodology was developed by the hospitality industry to create a consistent methodology for all hotels to measure and communicate their carbon impact. HCMI is currently being used by over 25,000 hotels globally. The ambition is that, through widespread use of HCMI, understanding, transparency, and accuracy across the industry will be improved.
Cornell Hotel Sustainability Benchmarking Index
The Cornell Hotel Sustainability Benchmarking Index (CHSB) is an industry-led global data collection and benchmarking initiative, with data on energy, water, and carbon emissions from over 20,000 hotels around the world. Participants in the CHSB index include major hotel brands, operators, and owners, representing all regions of the world.
The public dataset is published by Cornell’s School of Hospitality Research free of charge and contains average hotel performance for different types of hotels in different geographies. Hotels that participate directly in the index receive a confidential, bespoke benchmarking report showing how they are performing against their competitive set.
CHSB data is used by governments, corporate customers, travel management companies, and numerous other organizations to determine benchmarks and estimates for energy and water usage, and carbon footprints.
GHG Protocol
GHG Protocol establishes comprehensive global standardized frameworks to measure and manage greenhouse gas (GHG) emissions from private and public sector operations, value chains, and mitigation actions.
Building on a 20-year partnership between World Resources Institute (WRI) and the World Business Council for Sustainable Development (WBCSD), GHG Protocol works with governments, industry associations, NGOs, businesses, and other organizations.
### Sample API Requests
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "event",
"methodology": "HCMI",
"methodology_version": "2024",
"external_reference": "string",
"stars": 4,
"country": "FR",
"city": "Paris",
"state": "Ile-de-France",
"square_meters": 120,
"number_of_days": 2
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "event",
"methodology": "HCMI",
"methodology_version": "2024",
"external_reference": "string",
"stars": 4,
"country": "FR",
"city": "Paris",
"state": "Ile-de-France",
"square_meters": 120,
"number_of_days": 2
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### API Request Items
* `"type"`: `"event"` (required)
* `"methodology"`: `"HCMI"` (required)
* `"methodology_version"`: The HCMI/CHSB dataset year. Supported: `2015`–`2021`, `2023`, `2024`, `2026`. Omit or use `latest` for the latest stable year (`2026`).
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"stars"`: Stars is mutually exclusive with `hotel_type`; stars is prioritized over `hotel_type`. Minimum value is `1`, maximum value is `5`.
* `"country"`: Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively. Minimum length is `2`, maximum length is `3`.
* `"city"`
* `"state"`
* `"square_meters"`: Minimum value is `1`.
* `"number_of_days"`: Minimum value is `1`.
* `"hotel_type"`: `hotel_type` is mutually exclusive with `stars`, `stars` is prioritized over `hotel_type`. Available values include: `airport_location`, `convention_hotel`, `extended_stay`, `full_service_nonresort`, `full_service_resort`, `hotel_average`, etc. Default value is `"hotel_average"`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### Sample API Response
```json
{
"carbon_quantity": 3497,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 3497,
"carbon_unit": "gram",
"external_reference": "string",
"type": "event",
"methodology": "HCMI"
}
]
}
```
### Bibliography
* Ricaurte, Eric. *Hotel Sustainability Benchmarking Index 2024: Carbon, Energy, and Water*. 2024.
# Ferry
Ferries, pivotal in bridging geographical gaps, have distinct carbon footprints. The diversity in ferry sizes, propulsion methods, and routes contributes to varying emission rates. However, gauging the exact CO2 emissions for a specific ferry route, especially given the frequency of journeys and unpredictable weather conditions, is complex.
SQUAKE's cutting-edge solution streamlines this process. It tailors calculations for ferry-specific emissions, accommodating variances in size, route, and more. By leveraging SQUAKE, ferry operators and passengers can gain insight into their carbon impact, fostering more sustainable voyages across our waterways.
# Ferry: ADEME 🇫🇷
💡 **High-Level Description:**
ADEME, the French Agency for Ecological Transition, is renowned for its comprehensive methodologies addressing environmental issues, and its expertise extends to the carbon impact in multiple sectors. ADEME's approach towards carbon calculation in the ferry sector is emblematic of its broader commitment to a sustainable transport landscape. Recognizing that maritime transport plays a pivotal role in the global transportation matrix, the agency provides methodologies that allow for accurate measurement and eventual reduction of GHG emissions specific to ferries.
Within ferry transportation, ADEME's methodology takes into account the specific dynamics of maritime travel — such as fuel type, operational patterns, and varying capacities. This comprehensive approach helps stakeholders, including ferry operators and policymakers, to make informed decisions towards sustainable maritime transport. Moreover, it serves as an essential tool for meeting international emission reduction targets in the maritime sector.
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "ferry",
"methodology": "ademe",
"external_reference": "test_1",
"number_of_travelers": 3,
"origin": "Amsterdam, the Netherlands",
"destination": "Rotterdam, the Netherlands",
"number_of_cars": 1,
"vessel_type": "night_ferry"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "ferry",
"methodology": "ademe",
"external_reference": "test_1",
"number_of_travelers": 3,
"origin": "Amsterdam, the Netherlands",
"destination": "Rotterdam, the Netherlands",
"number_of_cars": 1,
"vessel_type": "night_ferry"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### **API Request Items**
* `"type"`: `"ferry"` (required)
* `"methodology"`: `"ADEME"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"origin"`: SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination`, and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"vessel_type"`: Values are `night_ferry`, `day_ferry`, `ro_pax`, or `river_vessel`. The default value is `day_ferry`.
* **Default Values**
* `"vessel_type": "day_ferry"`
### **Sample API Response**
```json
{
"carbon_quantity": 12015,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 12015,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "ferry",
"methodology": "ADEME",
"distance": 680.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* GHG information for transport services (2019, June). Ministère de La Transition Écologique et Solidaire. Retrieved from
# Flight
Passenger flights are integral to global connectivity, yet they contribute significantly to carbon emissions. Factors like aircraft model, flight duration, altitude, and even in-flight services can influence a plane's carbon footprint, rendering general estimations inadequate for precise calculations.
With SQUAKE's precision-based model, these intricacies are seamlessly integrated. This ensures that airlines and travelers have an accurate measure of the carbon footprint for each journey. Adopting SQUAKE allows for informed decisions towards sustainability, promoting eco-friendly skies for all.
For **multi-leg itineraries** described as a single hyphen-separated airport chain (for example `BER-FRA-JFK`) instead of origin and destination, see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
# Flight: Routing (multi-leg)
Flight routing lets API clients send a **single** flight item with an ICAO-style **hyphen-separated airport chain** (for example `BER-FRA-JFK`) instead of `origin` and `destination`. The backend expands that string into consecutive legs (BER→FRA, FRA→JFK), runs the same methodology **once per leg**, and **aggregates** carbon and distance on the parent item.
***
## Mutual exclusion with `origin` / `destination`
`routing` **cannot** be combined with `origin` or `destination`. Supplying both yields `invalid_params` with a detail such as:
`'routing' cannot be used together with 'origin' or 'destination'.`
***
## Parsing rules
The routing string is parsed as follows:
* Split on `-`, segments are converted to uppercase and trimmed.
* There must be **at least two** non-empty segments.
* **Consecutive segments must not be identical** (for example `BER-BER` is invalid).
Invalid or empty routing fails validation with a clear error, for example:
`'routing' must be a hyphen-separated list of at least two distinct airport codes (e.g. BER-FRA-JFK).`
***
## Per-leg parameters (pipe lists and defaults)
Certain attributes can vary **per leg**. Validated attributes include:
`booking_class`, `fare_class`, `airline`, `aircraft_type`, `aircraft_size`, `plane_type`, `biofuel`, `flight_number`, `departure_date`.
### How values are applied
* **Single value** — repeated for every leg.
* **Pipe-separated (`|`)** — must have **exactly as many parts as legs**. Leg count is the number of **consecutive airport pairs** in the routing (for `BER-FRA-JFK` there are **two** legs).
* **Hyphen split** — if the number of hyphen-separated segments **equals** the leg count, values map leg-by-leg. If that count does **not** match and the string is not a **single** segment, validation fails with an ambiguous multi-segment string.
* **`departure_date` is pipe-only** — it is never hyphen-split, because ISO dates contain hyphens. Use a single value (broadcast to all legs) or a pipe list with one entry per leg.
A **count mismatch** returns `invalid_params` with detail like:
`'booking_class' list has 2 value(s) but routing has 1 leg(s).`
Validation failures and leg-count mismatches also emit internal metrics for monitoring.
***
## `distance_in_km` when routing is present
`distance_in_km` is **not** used as a substitute for computed distance when routing is present: routing drives **per-leg** distance, and the parent item’s distance aggregates those legs. Submitting `distance_in_km` does **not** define the total for routed items.
***
## Response and `expand`
* Include **`"legs"`** in the request **`expand`** array (together with **`"items"`** when you need per-item totals) to receive a **per-leg** breakdown on the flight item.
* When `legs` is expanded, the item typically includes **`routing`** (echoing the submitted chain) and a **`legs`** array. Parent **`carbon_quantity`** and **`distance`** aggregate the legs (for example, parent `distance` matches the sum of leg distances).
* If **`expand`** includes only **`items`** (and omits **`legs`**), the item payload **may omit** `routing` and `legs` even when the request used routing.
With **audit mode** enabled, per-leg objects can include **`audit`** and **`emission_factors`** when `legs` is expanded.
***
## Example request
Multi-leg DEFRA flight with expanded items and legs:
```json
{
"expand": ["items", "legs"],
"carbon_unit": "tonne",
"distance_unit": "kilometer",
"items": [
{
"type": "flight",
"methodology": "DEFRA",
"routing": "BER-FRA-JFK",
"booking_class": "economy",
"number_of_travelers": 1,
"radiative_forcing_index": true,
"external_reference": "multi_leg_1"
}
]
}
```
Per-leg attributes example (two legs, different booking classes):
```json
{
"routing": "BER-FRA-JFK",
"booking_class": "economy|business"
}
```
# Flight: ADEME 🇫🇷
### :bulb: High-Level Description:
The French Environment and Energy Management Agency, ADEME (Agence de la transition écologique), is a renowned public institution at the forefront of environmental sustainability and energy management. Under the authority of the French Ministries of Ecology and Research, ADEME has gained recognition for its extensive research and its commitment to promoting sustainable practices across various sectors, including transportation, energy, and waste management.
Within the aviation sector, ADEME's methodologies are especially significant. Their carbon calculation approach is tailored specifically to account for the environmental footprint of passenger flights. By considering a comprehensive set of factors such as aircraft type, fuel consumption, flight duration, occupancy rates, and the inclusion of radiative forcing (which addresses the increased impact of emissions at higher altitudes), ADEME offers a nuanced and scientifically robust framework. This methodology empowers airlines, regulatory bodies, and environmental stakeholders to better understand and address the carbon emissions associated with air travel.
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "ADEME",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "JFK",
"aircraft_size": "under_180_seats",
"aircraft_type": "737",
"airline": "LH"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "ADEME",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "JFK",
"aircraft_size": "under_180_seats",
"aircraft_type": "737",
"airline": "LH"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### **API request items**
* `"type": "flight"` (required)
* `"methodology": "ADEME"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"aircraft_size"`: An estimation of the aircraft's size based on the number of seats. Values are `under_50_seats`, `under_100_seats`, `under_180_seats`, `under_250_seats`, or `over_250_seats`.
* `"aircraft_type"`: An IATA or ICAO code for the aircraft type.
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used. When **`routing`** is set, per-leg computed distances apply; see Flight: Routing.
* `"airline"`: The IATA Designator of an airline, e.g., LH. Airline names are also supported, SQUAKE will then automatically resolve it.
* `"sustainable_fuels"`: Indicates the usage of sustainable fuels. This lowers the computed emissions in SQUAKE but is not part of the current official emissions frameworks.
* `"carbon_reduction_percentage_of_total"`: The percentage of emissions reduction through the usage of sustainable fuel. The minimum value is `0`, and the maximum value is `1`. Default value is `0`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### **Sample API Response**
```json
{
"carbon_quantity": 632000,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 632000,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "flight",
"methodology": "ADEME",
"distance": 6320.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* GHG information for transport services (2019, June). Ministère de La Transition Écologique et Solidaire. Retrieved from
# Flight: Base Empreinte 🇫🇷
### :bulb: High-Level Description:
Base Empreinte, managed by ADEME, is a comprehensive environmental impact database combining data from Base Carbone and Base IMPACTS. For air travel, Base Empreinte® offers emissions data that reflect aircraft size, fuel type, and other parameters crucial for accurate carbon footprint assessments.
The methodology considers the radiative forcing index (RFI) to account for the broader climate impact of aviation emissions beyond CO2. This ensures that businesses and travelers receive comprehensive environmental insights into their air travel.
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "BASE-EMPREINTE",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "JFK",
"aircraft_size": "under_220_seats",
"radiative_forcing_index": true
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "BASE-EMPREINTE",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "JFK",
"aircraft_size": "under_220_seats",
"radiative_forcing_index": true
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### **API request items**
* `"type": "flight"` (required)
* `"methodology": "BASE-EMPREINTE"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used. When **`routing`** is set, per-leg computed distances apply; see Flight: Routing.
* `"aircraft_size"`: Supports values like `under_220_seats`, `under_50_seats`, `under_50_seats_jet`, or defaults to average if not passed.
* `"sustainable_fuels"`: Indicates the usage of sustainable fuels. This lowers the computed emissions in SQUAKE but is not part of the current official emissions frameworks.
* `"radiative_forcing_index"`: Defaults to `true`.
* `"carbon_reduction_percentage_of_total"`: The percentage of emissions reduction through the usage of sustainable fuel. The minimum value is `0`, and the maximum value is `1`. Default value is `0`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
* **Default Values**
* `"radiative_forcing_index": true`
### **Sample API Response**
```json
{
"carbon_quantity": 632000,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 632000,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "flight",
"methodology": "BASE-EMPREINTE",
"distance": 6320.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* ADEME. (2025). Base Empreinte - Données d’impacts environnementaux. Retrieved from
* ADEME. (2024). Base Carbone Methodological Guide. Retrieved from
* ADEME. (2023). Documentation on aviation emission factors. Available via official ADEME publications.
* Eurocontrol (2022). Aircraft performance and fuel consumption statistics.
# Flight: CO2 emissiefactoren 🇳🇱
### :bulb: High-Level Description:
CO2-emissiefactoren is a distinguished methodology originating from the Netherlands, designed to provide accurate emission factors across various sectors, including passenger aviation. With a focus on delivering clear and precise carbon metrics, the methodology is widely adopted by European stakeholders, offering them a reliable system for understanding and mitigating the carbon footprint of their activities.
Within the aviation sector, CO2-emissiefactoren's approach stands out for its ability to consider multiple factors, such as aircraft type, engine specifications, distance traveled, and fuel efficiency. The methodology is continually updated to reflect the latest research and technological developments, ensuring that the carbon calculations remain both current and comprehensive. By offering detailed insights into the carbon impact of air travel, CO2-emissiefactoren equips airlines, policymakers, and travelers with the tools necessary to make more sustainable choices in the aviation industry.
**Versioning:** Use `methodology_version` to pin a published factor year — `"2020"` for flights in 2020 and 2021, `"2022"` for flights from 2022 onward. If you omit it, SQUAKE picks the year from `departure_date`; if neither is given, the latest version is used. See **Versions** below.
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"external_reference": "string",
"origin": "MIL",
"destination": "ORY",
"booking_class": "first",
"energy_scope": "wtw",
"number_of_travelers": 1,
"radiative_forcing_index": true
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"external_reference": "string",
"origin": "MIL",
"destination": "ORY",
"booking_class": "first",
"energy_scope": "wtw",
"number_of_travelers": 1,
"radiative_forcing_index": true
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
**Defaults**
* `"booking_class": "average"`
* `"radiative_forcing_index": true`
* `"energy_scope": "wtw"`
* `"methodology_version"`: resolved from `departure_date`, or the latest version if no date is given
### **API request items**
* `"type": "flight"` (required)
* `"methodology": "CO2-EMISSIEFACTOREN-NL"` (required)
* `"methodology_version"`: The published factor year. Supported: `2020` (flights in 2020 and 2021) and `2022` (flights from 2022 onward). **Optional**; if omitted, the year is taken from `departure_date`, falling back to the latest version. See **Versions** below.
* `"departure_date"`: The date of departure in `YYYY-MM-DD` format. Used to select the factor year when `methodology_version` is omitted.
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"booking_class"`: If you don't pass a `booking_class`, then `fare_class` and `airline` are highly recommended. SQUAKE will then automatically resolve the correct `booking_class`. For `CO2-EMISSIEFACTOREN-NL`, this is optional with `average` as the default value. Values are `first`, `premium_economy`, `economy`, or `business`.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used. When **`routing`** is set, per-leg computed distances apply; see Flight: Routing.
* `"fare_class"`: The combination of `fare_class` and `airline` is mutually exclusive with `booking_class`. This is a single letter, e.g., `Y`, `J`, etc.
* `"radiative_forcing_index"`: Controls if a multiplier that factors in gases emitted to the atmosphere when flying at altitude should be applied. The default value is `true`.
* `"airline"`: The IATA Designator of an airline, e.g., LH. Airline names are also supported, SQUAKE will then automatically resolve it.
* `"energy_scope"`: Values are `ttw` or `wtw`. The default value is `wtw`.
* `"sustainable_fuels"`: Indicates the usage of sustainable fuels. This lowers the computed emissions in SQUAKE but is not part of the current official emissions frameworks.
* `"carbon_reduction_percentage_of_total"`: The percentage of emissions reduction through the usage of sustainable fuel. The minimum value is `0`, and the maximum value is `1`. Default value is `0`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### **Sample API Response**
```json
{
"carbon_quantity": 633654,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 633654,
"carbon_unit": "gram",
"external_reference": "string",
"type": "flight",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"distance": 749.0,
"distance_unit": "kilometer"
}
]
}
```
### **Versions**
CO2-emissiefactoren publishes flight factors per vintage. SQUAKE supports two:
| Version | Applies to | Notes |
| ------- | ------------------------ | ---------------------------------------------------------------- |
| `2020` | Flights in 2020 and 2021 | Factors are published per haul band only — no travel-class split |
| `2022` | Flights from 2022 onward | Factors are published per travel class and haul band |
SQUAKE picks the version in this order:
1. **An explicit `methodology_version`**, if you send one. This always wins, even when it disagrees with `departure_date`.
2. **The year of `departure_date`**, if no version was sent. A flight on `2020-05-01` or `2021-11-30` uses the `2020` factors; a flight on `2023-02-14` uses the `2022` factors.
3. **The latest version**, if neither is given.
A year that has no factor set of its own resolves to the most recent earlier year — `2021` resolves to `2020`, and `2023` and later resolve to `2022`. Years before `2020` are rejected with an `invalid_methodology_version` error.
The version actually used is returned as `methodology_version` on each item when you request `"expand": ["items"]`, so a calculation stays reproducible:
```json
{
"expand": ["items"],
"items": [
{
"type": "flight",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"origin": "MIL",
"destination": "ORY",
"departure_date": "2020-05-01",
"number_of_travelers": 1
}
]
}
```
```json
{
"carbon_quantity": 149800,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 149800,
"carbon_unit": "gram",
"type": "flight",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"methodology_version": "2020",
"distance": 749.0,
"distance_unit": "kilometer"
}
]
}
```
> **Note:** the `2020` factors have no travel-class dimension, so `booking_class` (and the `fare_class` + `airline` pair) does not change the result for flights priced with that version. Audit records for those calculations report the travel class actually priced, `average`.
For more details about RFI: [Radiative Forcing Index](https://squake.notion.site/Radiative-Forcing-Index-1f8f0d7eb6e141a6ad7a3351bdc53f05?pvs=4)
### **Bibliography**
* Lijst emissiefactoren (2025). CO2 emissionfactoren. Retrieved from
* Milieu Centraal (n.a.). Retrieved from
* Emissiefactoren van vliegverkeer in meer detail (Jan, 2022). MilieuCentraal. Retrieved from — factors for `methodology_version` `2022`
* Emissiefactoren van vliegverkeer (2020). MilieuCentraal. Retrieved from — factors for `methodology_version` `2020`
# Flight: DEFRA 🇬🇧
:bulb: **High-Level Description:**
The Department for Environment, Food, and Rural Affairs (DEFRA) of the United Kingdom plays a key role in shaping environmental policies and approaches to carbon reduction. As part of its sustainability initiatives, DEFRA has developed a carbon calculation methodology specifically for the flight passenger sector, providing a standardized and credible means to evaluate the emissions associated with air travel.
DEFRA's methodology for evaluating carbon emissions from passenger flights incorporates a range of factors. These include the aircraft's fuel consumption, flight distance, type of aircraft, and even the indirect effects of high-altitude emissions. The aim is to offer a holistic view of a flight's environmental impact. By developing this standardized approach, DEFRA not only aids the aviation industry in understanding and reducing its carbon footprint but also provides a reliable reference point for policymakers and environmental advocacy groups.
**Versioning:** Add `methodology_version` to pin a specific **Conversion Factors** year (e.g., `"2024"`). If omitted, SQUAKE **uses the latest supported year**.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "DEFRA",
"external_reference": "test_4",
"number_of_travelers": 2,
"origin": "LON",
"destination": "LAX",
"booking_class": "first",
"aircraft_type": "737",
"radiative_forcing_index": true,
"energy_scope": "wtw",
"methodology_version": "2024"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "DEFRA",
"external_reference": "test_4",
"number_of_travelers": 2,
"origin": "LON",
"destination": "LAX",
"booking_class": "first",
"aircraft_type": "737",
"radiative_forcing_index": true,
"energy_scope": "wtw",
"methodology_version": "2024"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
* **Default Values**
* `"booking_class": "average"`
* `"energy_scope": "wtw"`
* `"radiative_forcing_index": true`
* `"methodology_version"`: **latest supported DEFRA year (default if omitted)**
* **Calculation Specifics**
* An **8% uplift** is applied to Great Circle Distance (GCD) to account for indirect paths, delays, etc.
* If both `distance_in_km` and `origin`/`destination` are provided, **`distance_in_km` takes precedence**.
***
### **API Request Items**
* `"type": "flight"` **(required)**
* `"methodology": "DEFRA"` **(required)**
* `"methodology_version"`: DEFRA **Conversion Factors** year (e.g., `"2024"`). **Optional**; if omitted → **latest supported year**.
* `"external_reference"`: Unique identifier (max 128 chars).
* `"number_of_travelers"`: Minimum `1` (**default:** `1`).
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"distance_in_km"`: If present, **overrides** origin/destination resolution (not used as the routed total when **`routing`** is set; see Flight: Routing).
* `"booking_class"`: If not provided, pass `fare_class` + `airline` to auto-resolve; **default:** `"average"`.
* `"aircraft_type"`: IATA/ICAO code; **only applied when at least one airport is in the UK**.
* `"fare_class"` / `"airline"`: Mutually exclusive with `"booking_class"`.
* `"radiative_forcing_index"`: Apply high-altitude climate impact multiplier (**default:** `true`).
* `"sustainable_fuels"`: Indicates SAF use (reduces emissions in SQUAKE; not part of official DEFRA factors).
* `"carbon_reduction_percentage_of_total"`: Fraction `0–1` from SAF; **default:** `0`.
* `"energy_scope"`: `"wtw"` (**default**) or `"ttw"`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
### **Aircraft Type Distribution**
| Domestic | Short-Haul | Long-Haul |
| -------- | ---------- | --------- |
| 32N | 32N | 32N |
| 32Q | 32Q | 32Q |
| 319 | 318 | 320 |
| 320 | 319 | 321 |
| 321 | 320 | 332 |
| AT4 | 321 | 333 |
| AT5 | 332 | 339 |
| AT7 | 333 | 343 |
| 738 | 359 | 359 |
| D38 | AT7 | 338 |
| ER3 | 7M8 | 7M8 |
| ER4 | 7M9 | 738 |
| E70 | 733 | 752 |
| E90 | 734 | 763 |
| E95 | 735 | 764 |
| J41 | 736 | 772 |
| SF3 | 737 | 773 |
| | 738 | 77F |
| | 739 | 77W |
| | 752 | 788 |
| | 753 | 789 |
| | 763 | 781 |
| | 772 | |
| | 77W | |
| | 788 | |
| | 789 | |
| | 221 | |
| | 223 | |
| | CR9 | |
| | DH8 | |
| | E70 | |
***
### **Sample API Response**
```json
{
"carbon_quantity": 15273823,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 15273823,
"carbon_unit": "gram",
"external_reference": "test_4",
"type": "flight",
"methodology": "DEFRA",
"methodology_version": "2024",
"distance": 8804.0,
"distance_unit": "kilometer"
}
]
}
```
***
### **Versions**
* **Behavior:** If `methodology_version` is omitted, SQUAKE automatically applies the **latest supported** DEFRA Conversion Factors year. Pin a year for reproducibility and audit readiness.
***
### **Bibliography**
* UK Government — **Greenhouse gas emissions: Research & statistics**:
* Bramwell, R., et al. (2024). *Government Greenhouse Gas Conversion Factors for Company Reporting — Methodology*. (Methodology paper PDF).
# Flight: EPA 🇺🇸
### :bulb: High-Level Description:
The Environmental Protection Agency (EPA) has long been a vanguard in environmental preservation and protection in the United States. When it comes to carbon calculations for the flight passenger sector, the EPA's methodology offers a robust framework, bearing in mind the intricate nature of aviation and its environmental implications. As the aviation industry remains a considerable contributor to greenhouse gas emissions, it becomes crucial to possess a comprehensive and accurate calculation methodology.
The EPA's approach for carbon emissions from passenger flights emphasizes not just the direct emissions but also factors in relevant elements such as plane type, flight distance, fuel efficiency, and load factors. This multifaceted methodology assists airlines, regulatory bodies, and environmental advocates in gaining a clearer understanding of the sector's carbon footprint. The consistency this approach provides ensures that carbon reduction efforts are based on reliable data, making it possible to chart effective and impactful strategies to combat climate change.
**Versioning:** Include `methodology_version` to pin a specific Hub year (e.g., `"2024"`). If omitted, SQUAKE **uses the latest supported year**.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "US-EPA",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "JFK",
"destination": "ORY",
"methodology_version": "2024"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "US-EPA",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "JFK",
"destination": "ORY",
"methodology_version": "2024"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### **API Request Items**
* `"type": "flight"` **(required)**
* `"methodology": "US-EPA"` **(required)**
* `"methodology_version"`: EPA Hub year (e.g., `"2024"`). **Optional**; if omitted → **latest supported year**.
* `"external_reference"`: Correlates request/response (max 128 chars).
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"distance_in_km"`: If provided, **overrides** origin/destination resolution (not used as the routed total when **`routing`** is set; see Flight: Routing).
* `"sustainable_fuels"`: Indicates SAF usage (reduces emissions in SQUAKE; not part of EPA factors).
* `"carbon_reduction_percentage_of_total"`: Fraction `0–1` applied when `sustainable_fuels` is used (**default:** `0`).
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
> Notes: EPA provides mode-level factors; aircraft-specific parameters (type, booking class, RFI) are not part of EPA Hub factors.
***
### **Sample API Response**
```json
{
"carbon_quantity": 625550,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 625550,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "flight",
"methodology": "US-EPA",
"methodology_version": "2024",
"distance": 5964.0,
"distance_unit": "kilometer"
}
]
}
```
***
### **Versions**
* **Behavior:** If `methodology_version` is omitted, SQUAKE automatically applies the **latest supported** EPA Hub year. Pin a year for reproducibility and auditability.
***
### **Bibliography**
* **US EPA — GHG Emission Factors Hub**:
# Flight: GATE4
:bulb: **High-Level Description:**
GATE4 is a carbon emissions calculation methodology developed by Advito, tailored for the travel sector with a particular focus on flights. Embracing a holistic sustainability approach, GATE4 captures a broad range of factors to produce a detailed and accurate assessment of travel-related carbon emissions. For flights, variables such as aircraft type, passenger-to-freight ratios, carbon intensity, and the effect of radiative forcing are carefully accounted for. This comprehensive method allows organizations to accurately track emissions and devise strategies to mitigate their environmental impact.
The GATE4 methodology is ISO-certified, which adds a layer of credibility and ensures that its calculations align with international environmental management standards. By utilizing real-time data integration, it provides travel managers with actionable insights through the GATE4 Insights dashboard, covering not just air travel but also hotel stays, rail journeys, and car rentals. This enables businesses to identify opportunities to reduce emissions, optimize travel choices, and align their practices with sustainability goals. GATE4’s robust data-driven approach supports the development of science-based sustainability targets, helping organizations contribute effectively to global carbon reduction efforts.
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "GATE4",
"origin": "NBO",
"destination": "ABJ",
"number_of_travelers": 1,
"booking_class": "business",
"airline": "2J",
"flight_number": "2J520",
"external_reference": "test",
"departure_date": "2024-10-01"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "GATE4",
"origin": "NBO",
"destination": "ABJ",
"number_of_travelers": 1,
"booking_class": "business",
"airline": "2J",
"flight_number": "2J520",
"external_reference": "test",
"departure_date": "2024-10-01"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
### **API Request Items**
* `"type": "flight"` (required)
* `"methodology": "GATE4"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"origin"`: For airports use IATA codes (format: `^[A-Z]{3}$`, e.g. `"MUC"`).
* `"destination"`: For airports use IATA codes (format: `^[A-Z]{3}$`, e.g. `"MUC"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"booking_class"`: If you don't pass a `booking_class`, then `fare_class` and `airline` are highly recommended. SQUAKE will then automatically resolve the correct `booking_class`. For `GATE4`, `economy` is the default.
* `"aircraft_type"`: Aircraft type in the IATA or ICAO format.
* `"fare_class"`: The combination of `fare_class` and `airline` is mutually exclusive with `booking_class`. This is a single letter, e.g., `Y`, `J`, etc.
* `"airline"`: The IATA Designator of an airline, e.g., `LH`. Airline names are also supported, SQUAKE will then automatically resolve it. The combination of `fare_class` and `airline` is mutually exclusive with `booking_class`.
* `"flight_number"`: Flight numbers should include the airline designator, e.g., `"BA115"`. `"115"` also works with `airline` passed separately.
* `"departure_date"`: The departure date in the format `YYYY-MM-DD`, which is aligned with [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
* `"sustainable_fuels"`: Indicates the usage of sustainable fuels. This lowers the computed emissions in SQUAKE but is not part of the current official emissions frameworks.
* `"carbon_reduction_percentage_of_total"`: The percentage of emissions reduction through the usage of sustainable fuel. The minimum value is `0`, and the maximum value is `1`. Default value is `0`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### **Sample API Response**
```json
{
"carbon_quantity": 1078043,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 1078043,
"carbon_unit": "gram",
"external_reference": "test",
"type": "flight",
"methodology": "GATE4",
"distance": 4700.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* Accurately Measure Your Travel Emissions with GATE4 (2024, Sep). Advito. Retrieved from
# Flight: ICAO
💡 **High-Level Description:**
The International Civil Aviation Organization (ICAO) plays a pivotal role in guiding aviation-related environmental policies on a global scale. Recognizing the aviation industry's significant carbon footprint, ICAO has developed methodologies specifically tailored to the flight passenger sector, aimed at determining its environmental impact. The overarching goal is to facilitate a harmonized global approach to address greenhouse gas emissions from aviation.
ICAO's carbon calculation methodology incorporates several variables, including aircraft type, flight distance, fuel burn rates, and passenger load factors. These metrics are then standardized across all member states, providing a cohesive measurement standard. By implementing such comprehensive strategies, ICAO not only helps industries to identify areas of improvement but also sets the foundation for global initiatives such as the Carbon Offsetting and Reduction Scheme for International Aviation (CORSIA), targeting a carbon-neutral growth for international aviation from 2020.
**The ICAO methodology does not include the ICEC dataset.**
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "ICAO",
"external_reference": "test_7",
"origin": "BER",
"destination": "JFK",
"aircraft_type": "737",
"number_of_travelers": 1,
"booking_class": "business",
"airline": "AA",
"fare_class": "Y"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "ICAO",
"external_reference": "test_7",
"origin": "BER",
"destination": "JFK",
"aircraft_type": "737",
"number_of_travelers": 1,
"booking_class": "business",
"airline": "AA",
"fare_class": "Y"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
* **Default Values**
* `"booking_class": "economy"`
* `"aircraft_type": "737"` for flights under `550` km
* `"aircraft_type": "321"` for flights under `5500` and above `550` km
* `"aircraft_type": "320"` for flights above `5500` km
### **Calculation Specifics**
**CO2 per pax = 3.16 \* (total fuel \* pax-to-freight factor) / (number of Y-seats \* pax load factor)**
* **Total fuel**: The weighted average of the fuel used by all flights departing from the origin airport to reach the destination airport. The weighting factor is the ratio of the number of departures for each equivalent aircraft type to the total number of departures.
* **Pax-to-freight factor**: The ratio calculated from the ICAO statistical database based on the number of passengers and the tonnage of mail and freight transported in a given route group.
* **Number of Y-seats**: The total number of economy-equivalent seats available on all flights serving the given city pair.
* **Pax load factor**: The ratio calculated from the ICAO statistical database based on the number of passengers transported and the number of seats available in a given route group.
3.16 is a constant representing the tonnes of CO2 produced by burning one tonne of aviation fuel.
The methodology uses the Great Circle Distance (GCD) between airports as input to calculate the fuel used, and thus estimate CO2 emissions. GCD is by definition the shortest distance between two points on the surface of a sphere. This distance can be calculated by using the geographical coordinates of the two points concerned. The coordinates for the airports involved are obtained from the ICAO Location Indicators database (ICAO Doc 7910). Once the GCD is calculated, it is then corrected by a factor depending on the distance between the two airports concerned. The correction factor is needed in order to include the emissions of distance flown in excess of the GCD, stacking, traffic and weather-driven corrections. According to EIG, the actual distance flown compared with GCD that is given in the scheduled flights timetable may vary up to 11% in Europe (ANCAT/EC2 1998).
| **GCD** | **Correction to GCD** |
| -------------------------- | --------------------- |
| Less than 550 Km | + 50 Km |
| Between 550 Km and 5500 Km | + 100 Km |
| Over 5500 Km | + 125 Km |
### **API Request Items**
* `"type": "flight"` (required)
* `"methodology": "ICAO"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"booking_class"`: If you don't pass a `booking_class`, then `fare_class` and `airline` are highly recommended. SQUAKE will then automatically resolve the correct `booking_class`. For `ICAO`, `economy` is the default.
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used. When **`routing`** is set, per-leg computed distances apply; see Flight: Routing.
* `"aircraft_type"`: Aircraft type in the IATA or ICAO format.
* `"fare_class"`: The combination of `fare_class` and `airline` is mutually exclusive with `booking_class`. This is a single letter, e.g., `Y`, `J`, etc.
* `"airline"`: The IATA Designator of an airline, e.g., `LH`. Airline names are also supported, SQUAKE will then automatically resolve it. The combination of `fare_class` and `airline` is mutually exclusive with `booking_class`.
* `"sustainable_fuels"`: Indicates the usage of sustainable fuels. This lowers the computed emissions in SQUAKE but is not part of the current official emissions frameworks.
* `"carbon_reduction_percentage_of_total"`: The percentage of emissions reduction through the usage of sustainable fuel. The minimum value is `0`, and the maximum value is `1`. Default value is `0`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### **Sample API Response**
```json
{
"carbon_quantity": 454070,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 454070,
"carbon_unit": "gram",
"external_reference": "test_7",
"type": "flight",
"methodology": "ICAO",
"distance": 6522.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* ICAO Carbon Emissions Calculator Methodology Version 13.1 (2024, Aug). ICAO. Retrieved from [https://applications.icao.int/icec/Methodology ICAO Carbon Emissions Calculator\_v13\_Final.pdf](https://applications.icao.int/icec/Methodology%20ICAO%20Carbon%20Emissions%20Calculator_v13_Final.pdf)
# Flight: TIM
💡 **High-Level Description:**
The Travel Impact Model (TIM), developed under the aegis of Google and its independent Advisory Committee, revolutionizes the carbon footprint estimation for air freight, employing a cutting-edge, comprehensive methodology. Drawing from public and licensable datasets, TIM meticulously calculates per-seat or per-passenger CO2e emissions by considering a range of variables including flight details, aircraft specifics, and load factors, ensuring a robust and transparent emission estimate. Notably, TIM's methodology stands apart for its dedication to accuracy, validated against real-world data, and its ambition to cover the complete climate impacts of aviation, making it a future-proof tool that evolves alongside aviation technologies and practices.
By focusing on the precise calculation of emissions and offering these insights through a freely accessible API, TIM empowers stakeholders across the aviation sector—from airlines to passengers—to make informed decisions regarding their carbon footprint. The model's governance structure, featuring a mix of industry, academic, and policy experts, guarantees that TIM remains at the forefront of scientific advancement, maintaining its relevance and utility in facilitating sustainable aviation practices.
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "TIM",
"origin": "SYD",
"destination": "MEL",
"number_of_travelers": 1,
"booking_class": "economy",
"airline": "QF",
"flight_number": "QF0479",
"aircraft_type": "73H",
"external_reference": "test",
"energy_scope": "wtw",
"logistics_hub": true
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "TIM",
"origin": "SYD",
"destination": "MEL",
"number_of_travelers": 1,
"booking_class": "economy",
"airline": "QF",
"flight_number": "QF0479",
"aircraft_type": "73H",
"external_reference": "test",
"energy_scope": "wtw",
"logistics_hub": true
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
* **Default Values**
* `"booking_class": "economy"`
* `"energy_scope": "wtw"`
* `"logistics_hub": false`
### **API Request Items**
* `"type": "flight"` (required)
* `"methodology": "TIM"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. The default value is `1`.
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`). ⚠️ To achieve higher accuracy (Tier 1 or 2), IATA codes should be used.
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`). ⚠️ To achieve higher accuracy (Tier 1 or 2), IATA codes should be used.
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"booking_class"`: If you don't pass a `booking_class`, then `fare_class` and `airline` are highly recommended. SQUAKE will then automatically resolve the correct `booking_class`. For `TIM`, `economy` is the default.
* `"aircraft_type"`: Aircraft type in the IATA or ICAO format.
* `"fare_class"`: The combination of `fare_class` and `airline` is mutually exclusive with `booking_class`. This is a single letter, e.g., `Y`, `J`, etc.
* `"airline"`: The IATA Designator of an airline, e.g., `LH`. Airline names are also supported, SQUAKE will then automatically resolve it. The combination of `fare_class` and `airline` is mutually exclusive with `booking_class`.
* `"flight_number"`: Flight numbers should include the airline designator, e.g., `"BA115"`. `"115"` also works with `airline` passed separately.
* `"departure_date"`: The departure date in the format `YYYY-MM-DD`, which is aligned with [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
* `"sustainable_fuels"`: Indicates the usage of sustainable fuels. This lowers the computed emissions in SQUAKE but is not part of the current official emissions frameworks.
* `"carbon_reduction_percentage_of_total"`: The percentage of emissions reduction through the usage of sustainable fuel. The minimum value is `0`, and the maximum value is `1`. Default value is `0`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"logistics_hub"`: Adds airport emissions (1.71 kg CO₂e per airport), so 3.42 kg CO₂e per item. Use `true` for full end-to-end journey per ISO 14083. Default is `false`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### **Sample API Response**
```json
{
"carbon_quantity": 78418,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 78418,
"carbon_unit": "gram",
"external_reference": "test",
"type": "flight",
"methodology": "TIM",
"distance": 706.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"dataset_type": "google_tim",
"contrails_impact_bucket": "MODERATE"
}
}
]
}
```
### **API Response Items: Algorithm Specifics**
* `"dataset_type": "google_tim"`\
Refers to the standard Travel Impact Model (TIM) methodology. This uses current and modeled flight data to estimate emissions based on flight-specific variables such as aircraft type, route, and cabin class. It ensures high accuracy and is aligned with TIM's publicly documented methodology.
* `"dataset_type": "google_tim_fallback"`\
Indicates that the input data provided was insufficient for precise matching, so a fallback logic was applied by SQUAKE to estimate emissions. This may occur if essential data like flight number or airline is missing, or cannot be matched reliably. The fallback method may lead to less accurate results but still provides a reasoned approximation.
* `"dataset_type": "historical_google_tim"`\
Refers to TIM's historical emissions dataset, structured into three tiers based on data availability and accuracy. The tiers represent a hierarchy of precision:
* **Tier 1**: `TIM past direct flight emissions`
* Requires: Carrier, Flight Number, Origin, Destination, Departure Date, Cabin Class
* Use: For direct flights only
* Accuracy: **Highest**
* Description: Uses actual scheduled flight data from 2019, covering operating and codeshare flights. Provides the most accurate CO₂e estimate when full flight details are known.
* **Tier 2**: `Typical flight emissions`
* Requires: Origin, Destination, Cabin Class
* Use: For direct **or indirect** flights
* Accuracy: **Medium**
* Description: Uses typical emissions based on historical routes between two airports, averaging over multiple possible flight paths. Useful when flight numbers or dates are unknown.
* **Tier 3**: `Distance-based emission factors`
* Requires: Distance travelled, Cabin Class
* Use: For direct **or indirect** flights
* Accuracy: **Lowest**
* Description: Applies generalized emission factors per kilometer per seat, segmented by cabin class. Should be used only when flight routing data is unavailable.
* `"contrails_impact_bucket"`: Indicates the estimated climate warming risk from contrails for the flight. Values are `"UNSPECIFIED"`, `"NEGLIGIBLE"`, `"MODERATE"`, or `"SEVERE"`, based on how the contrail impact compares to the flight’s fuel burn emissions. This is for display only — it is not converted into CO₂e or combined with fuel emissions.
### **Bibliography**
* \[External] Travel Impact Model Emissions Data. TIM Team. For more details, check:
# Flight: TU Chalmers 🇸🇪
### 💡 High-Level Description:
The **TU-Chalmers methodology** originates from research conducted by Chalmers University of Technology, one of Sweden’s leading institutions in environmental and energy sciences. This methodology is grounded in academic research that focuses on improving the precision of greenhouse gas (GHG) calculations for air travel. It integrates detailed parameters such as booking class, flight type (scheduled or charter), and the use of biofuels to offer a refined understanding of aviation emissions.
TU-Chalmers stands out for its consideration of passenger class-specific emissions (reflecting differences in space usage and associated fuel allocation) and for enabling assessments of flights utilizing biofuels. This approach is particularly beneficial for academic institutions, sustainability auditors, and airlines aiming to implement climate-conscious travel policies and carbon reporting practices.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "flight",
"methodology": "TU-CHALMERS",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "JFK",
"booking_class": "premium_economy",
"plane_type": "scheduled",
"biofuel": true
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "flight",
"methodology": "TU-CHALMERS",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "JFK",
"booking_class": "premium_economy",
"plane_type": "scheduled",
"biofuel": true
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### **API Request Items**
* `"type": "flight"` (required)
* `"methodology": "TU-CHALMERS"` (required)
* `"external_reference"`: A unique identifier to help link the resulting emissions to the specific request. This is useful when multiple items are submitted. Max length is 128 characters.
* `"number_of_travelers"`: Minimum value is `1`. Default value is `1`.
* `"origin"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* `"destination"`: For airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g. `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g. `"+40.712,-74.006"`).
* Multi-leg itineraries: use **`routing`** (hyphen-separated airports) instead of `origin`/`destination` — see [**Flight: Routing (multi-leg)**](/api-calculations-request-response/travel/flight/flight-routing).
* `"distance_in_km"`: If provided, it overrides `origin` and `destination`. If omitted, distance is resolved automatically using `origin` and `destination` (not used as the routed total when **`routing`** is set; see Flight: Routing).
* `"booking_class"`: Indicates the travel class. Supported values include: `economy`, `premium_economy`, `business`, and `first`. This affects emissions based on the space and resource allocation per passenger.
* `"plane_type"`: Specifies whether the flight is a `"scheduled"` service or a `"charter"` flight. Default value is `"scheduled"`.
* `"biofuel"`: A boolean (`true` or `false`) indicating whether biofuel was used for the flight. Default is `false`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
### **Sample API Response**
```json
{
"carbon_quantity": 632000,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 632000,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "flight",
"methodology": "TU-CHALMERS",
"distance": 6320.0,
"distance_unit": "kilometer"
}
]
}
```
***
### **Bibliography**
* Methodology Report for Travel and Climate (Version 4.1). Chalmers University of Technology. Retrieved from
# Hotel
The hospitality industry, particularly hotels, plays a significant role in carbon emissions, encompassing energy usage for heating, cooling, lighting, and daily operations. Beyond just the infrastructure, it is also daily activities, laundry, waste management, and food services that contribute to a hotel's carbon impact, making it essential for establishments to monitor and reduce their emissions.
SQUAKE provides a precise solution for hotels, enabling them to calculate and showcase their carbon emissions accurately. By integrating with SQUAKE, hotels can adopt sustainable practices, guide guests towards eco-friendly choices, and position themselves as leaders in environmentally responsible hospitality.
## Methodologies
* [Hotel: DEFRA](/api-calculations-request-response/travel/hotel/hotel-defra)
* [Hotel: GreenView](/api-calculations-request-response/travel/hotel/hotel-greenview)
* [Hotel: HCMI & CHSB](/api-calculations-request-response/travel/hotel/hotel-hcmi)
* [Hotel: NOS-GESTES-CLIMAT](/api-calculations-request-response/travel/hotel/hotel-nos-gestes-climat)
# Hotel: DEFRA 🇬🇧
💡 **High-Level Description**
The UK's Department for Environment, Food & Rural Affairs (DEFRA) has been instrumental in pioneering carbon accounting standards across various sectors. In the hotel industry, the DEFRA methodology emphasizes transparency and consistency. Recognizing the varied energy consumption patterns of different hotel types, from luxury resorts to budget motels, DEFRA guidelines are designed to cater to this diversity. They factor in direct energy use, including heating, cooling, and electricity consumption, but also delve into indirect emissions. This includes emissions from supply chain activities, food and beverage services, waste disposal, and guest transportation.
What sets the DEFRA methodology apart is its emphasis on adaptability and continuous improvement. Hotels are encouraged to not just measure and report their carbon footprint but to also undertake actions towards reducing it. By providing specific guidance on carbon reduction strategies, from energy-efficient appliances to waste reduction initiatives, DEFRA's approach ensures that the hotel sector can actively contribute to broader sustainability goals.
**Versioning:** Add `methodology_version` to pin a specific **Conversion Factors** year (e.g., `"2024"`). If omitted, SQUAKE **uses the latest supported year**.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "hotel",
"methodology": "DEFRA",
"external_reference": "string",
"country": "GB",
"city": "London",
"number_of_nights": 2,
"methodology_version": "2024"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "hotel",
"methodology": "DEFRA",
"external_reference": "string",
"country": "GB",
"city": "London",
"number_of_nights": 2,
"methodology_version": "2024"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### **API Request Items**
* `"type"`: `"hotel"` **(required)**
* `"methodology"`: `"DEFRA"` **(required)**
* `"methodology_version"`: DEFRA **Conversion Factors** year (e.g., `"2024"`). **Optional**; if omitted → **latest supported year**.
* `"external_reference"`: Correlate response to request (max 128 chars).
* `"country"`: ISO 3166-1 alpha-2/alpha-3 code (min 2, max 3).
* `"city"`: Only `"London"` within `"GB"` is supported.
* `"number_of_nights"`: Minimum `1`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
### **Default values**
* `"country": "GB"`
* `"methodology_version"`: **latest supported DEFRA year**
***
### **Sample API Response**
```json
{
"carbon_quantity": 23000,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 23000,
"carbon_unit": "gram",
"external_reference": "string",
"type": "hotel",
"methodology": "DEFRA",
"methodology_version": "2024"
}
]
}
```
***
### **Versions**
* **Behavior:** If `methodology_version` is omitted, SQUAKE automatically applies the **latest supported** DEFRA Conversion Factors year. Pin a specific year for reproducibility and auditability.
***
## **Bibliography**
* UK Government — **Greenhouse gas emissions: Research & statistics**:
* *Government Greenhouse Gas Conversion Factors for Company Reporting — Methodology* (latest year).
# Hotel: GreenView
💡 **High-Level Description**
The **GreenView Hotel Footprinting Tool (HFT)** is a robust, industry-recognized dataset that provides carbon footprint coefficients for hotel stays and meeting spaces worldwide. It is based on the **Cornell Hotel Sustainability Benchmarking Index (CHSB)** data, offering more granularity and updated figures.
The GreenView HFT dataset:
* Covers \~200 countries, 100 sub-national regions, and 450 market areas.
* Includes coefficients segmented by hotel star rating (2–5 stars) and hotel average.
* Is updated annually and adapted from the latest CHSB dataset.
* Is intended for integration into hotel emissions calculations and sustainability reporting.
GreenView HFT enables Online Booking Tools (OBTs), Travel Management Companies (TMCs), Online Travel Agencies (OTAs), and other stakeholders to calculate and communicate hotel emissions with improved accuracy and transparency.
**Versioning:** Add `methodology_version` to pin a specific GreenView HFT dataset year (e.g., `"2024"`). If omitted, SQUAKE **uses the latest supported year**.
***
### Sample API Requests
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "hotel",
"methodology": "GREENVIEW",
"external_reference": "string",
"country": "AU",
"city": "Sydney",
"stars": 4,
"number_of_nights": 1,
"methodology_version": "2024"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "hotel",
"methodology": "GREENVIEW",
"external_reference": "string",
"country": "AU",
"city": "Sydney",
"stars": 4,
"number_of_nights": 1,
"methodology_version": "2024"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### API Request Items
* `"type"`: `"hotel"` (required)
* `"methodology"`: `"GREENVIEW"` (required)
* `"methodology_version"`: GreenView HFT dataset year (`"2021"` – `"2026"`). **Optional**; if omitted → **latest supported year**.
* `"external_reference"`: A unique identifier that helps link the resulting emissions to the requested item. Maximum length: 128 characters.
* `"country"`: ISO-2 or 3 code of the country.
* `"city"`: Full city name. The full list of the supported cities is [here](https://squake.notion.site/237754e0050481838a1deea7dc0a7ba0?v=237754e00504812aba8d000c4b480cf4\&source=copy_link).
* `"state"`: Full state name. The full list of the supported states is [here](https://squake.notion.site/237754e005048191a59ef561244c09b0?v=237754e0050481758081000c23e8e4dd\&source=copy_link).
* `"stars"`: Hotel star rating from 1 to 5. If unavailable or unsupported for a specific location, falls back to hotel average.
* `"number_of_nights"`: Number of nights. Minimum value: 1.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
### Default values
* `"methodology_version"`: **latest supported GreenView year**
***
### Default Logic
📍 **Location hierarchy**
1. If `city` data is unavailable → fallback to `state`.
2. If `state` data is unavailable → fallback to `country`.
3. If `country` data is unavailable → fallback to `continent`.
⭐ **Stars fallback**
1. If data for specified `stars` is unavailable → fallback to `hotel_average`.
2. If no `stars` are passed → use `hotel_average`.
3. If no location is known → default to `32.69` kgCO₂e per night.
***
### Sample API Response
```json
{
"carbon_quantity": 16193,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 16193,
"carbon_unit": "gram",
"external_reference": "string",
"type": "hotel",
"methodology": "GREENVIEW",
"methodology_version": "2024"
}
]
}
```
***
### Versions
* **Supported range:** `2021` – `2026`
* **Behavior:** If `methodology_version` is omitted, SQUAKE automatically applies the **latest supported** GreenView HFT year. Pin a specific year for reproducibility and auditability.
***
### Notes
* Use the following citation when using the dataset:
> *Greenview Hotel Footprinting Tool Version 2024v1.1 (adapted from CHSB2024 data set of 2022 calendar year data).*
If the data is modified or adjusted, include a clear note in the citation.
***
## Bibliography
* Greenview. *Hotel Footprinting Tool Version 2024*. Greenview Hospitality Pte. Ltd., adapted from CHSB 2024.
* Ricaurte, Eric. *Hotel Sustainability Benchmarking Index 2024: Carbon, Energy, and Water*. Cornell University, 2024.
# Hotel: NOS-GESTES-CLIMAT
## High-Level Description
NOS-GESTES-CLIMAT uses a fixed hotel footprint per night from Nos Gestes Climat. SQUAKE calculates hotel emissions with a simple per-night factor:
```
hotel_co2e_kg = 6.94 * number_of_nights
```
The method does not require location, hotel class, room type, or methodology version inputs.
### Sample API Request
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "hotel",
"methodology": "NOS-GESTES-CLIMAT",
"external_reference": "hotel-ngc-1",
"number_of_nights": 2
}
]
}
```
### API Request Items
* `"type"`: `"hotel"` (required)
* `"methodology"`: `"NOS-GESTES-CLIMAT"` (required)
* `"number_of_nights"`: Number of nights. Required, numeric, and minimum `1`.
* `"external_reference"`: A reference ID that links the resulting emissions to the request. Maximum length: 128 characters.
* `"audit"`: boolean (optional). Use `true` when you create immutable audit records for final calculations. Your account must have audit mode enabled.
### Sample API Response
```json
{
"carbon_quantity": 13880,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 13880,
"carbon_unit": "gram",
"external_reference": "hotel-ngc-1",
"type": "hotel",
"methodology": "NOS-GESTES-CLIMAT",
"algorithm_specifics": {
"factor_kg_co2e_per_night": 6.94,
"factor_g_co2e_per_night": 6940,
"number_of_nights": 2
}
}
]
}
```
## Bibliography
* Nos Gestes Climat documentation:
* Nos Gestes Climat model:
* Nos Gestes Climat GitHub model repository:
# Hotel: HCMI & CHSB
💡 **High-Level Description**
The Hotel Carbon Measurement Initiative (HCMI) and the Cornell Hotel Sustainability Benchmarking Index (CHSB) are two prominent methodologies within the hotel industry, specifically tailored to measure carbon footprints and promote sustainable practices. The HCMI, a global standard introduced by leading hotel chains and organizations, focuses on providing a consistent method to calculate and communicate the carbon footprint of hotel stays and meetings. It considers variables like energy and water usage, waste production, and even outsourced services.
On the other hand, the CHSB, pioneered by Cornell University's School of Hotel Administration, serves as an index that allows hotels worldwide to benchmark their energy and water usage, greenhouse gas emissions, and other sustainability metrics against peer institutions. By collating data from diverse geographical regions and hotel sizes, CHSB equips hoteliers with vital insights to improve their environmental efficiency and sustainability credentials, ensuring they remain competitive in an increasingly eco-conscious global market.
Hotel Carbon Measurement Initiative
Hotel Carbon Measurement Initiative (HCMI) is a free methodology and tool for hotels to calculate the carbon footprint of hotel stays and meetings in their properties.
The methodology was developed by the hospitality industry to create a consistent methodology for all hotels to measure and communicate their carbon impact. HCMI is currently being used by over 25,000 hotels globally. The ambition is that, through widespread use of HCMI, understanding, transparency, and accuracy across the industry will be improved.
Cornell Hotel Sustainability Benchmarking Index
The Cornell Hotel Sustainability Benchmarking Index (CHSB) is an industry-led global data collection and benchmarking initiative, with data on energy, water, and carbon emissions from over 20,000 hotels around the world. Participants in the CHSB index include major hotel brands, operators, and owners, representing all regions of the world.
The public dataset is published by Cornell’s School of Hospitality Research free of charge and contains average hotel performance for different types of hotels in different geographies. Hotels that participate directly in the index receive a confidential, bespoke benchmarking report showing how they are performing against their competitive set.
CHSB data is used by governments, corporate customers, travel management companies, and numerous other organizations to determine benchmarks and estimates for energy and water usage, and carbon footprints.
GHG Protocol
GHG Protocol establishes comprehensive global standardized frameworks to measure and manage greenhouse gas (GHG) emissions from private and public sector operations, value chains, and mitigation actions.
Building on a 20-year partnership between World Resources Institute (WRI) and the World Business Council for Sustainable Development (WBCSD), GHG Protocol works with governments, industry associations, NGOs, businesses, and other organizations.
### Sample API Requests
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "hotel",
"methodology": "HCMI",
"methodology_version": "2024",
"external_reference": "string",
"country": "AU",
"city": "Villa La Angostura",
"hotel_type": "urban_location",
"stars": 4,
"hcmi_member": false,
"number_of_nights": 1
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "hotel",
"methodology": "HCMI",
"methodology_version": "2024",
"external_reference": "string",
"country": "AU",
"city": "Villa La Angostura",
"hotel_type": "urban_location",
"stars": 4,
"hcmi_member": false,
"number_of_nights": 1
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
#### C. By floor area (`square_meters`)
Provide `square_meters` to calculate by floor area instead of per occupied room. `square_meters` takes precedence over `number_of_nights`.
```json
{
"expand": ["items"],
"items": [
{
"type": "hotel",
"methodology": "HCMI",
"methodology_version": "2024",
"country": "FR",
"city": "Paris",
"stars": 4,
"square_meters": 120
}
]
}
```
### API Request Items
* `"type"`: `"hotel"` (required)
* `"methodology"`: `"HCMI"` (required)
* `"external_reference"`: A unique identifier that helps link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"stars"`: Stars is mutually exclusive with `hotel_type`; stars is prioritized over `hotel_type`. Minimum value is `1`, maximum value is `5`.
* `"country"`: Two-letter or three-letter code as defined in ISO 3166-1 alpha-2 and alpha-3 respectively. Minimum length is `2`, maximum length is `3`.
* `"city"`: Here is [the database](https://squake.notion.site/173c4b5d045a4e5dbea2b72d5c6a385f?v=0c94e9d12afb4cdd92be1d751797cd99\&pvs=4)
* `"state"`: Here is [the database](https://squake.notion.site/9b5019f84a71458bb62d87864bdb9e39?v=32f49ed805504bf7ab419e90fb743b68\&pvs=4)
* `"hcmi_member"`:`true` or `false`.
* `"number_of_nights"`: Minimum value is `1`.
* `"methodology_version"`: The HCMI/CHSB dataset year. Supported: `2015`–`2021`, `2023`, `2024`, `2026`. Omit or use `latest` for the latest stable year (`2024`). Years without a dataset (`2022`, `2025`) resolve to the nearest earlier year.
* `"square_meters"`: Optional. When provided, the hotel is calculated by floor area using the per-square-metre dataset; takes precedence over `number_of_nights`. Minimum value is `1`.
* `"account_for_total"`: `true` or `false` (default `false`). `false` uses the HCMI Rooms Footprint per occupied room; `true` uses the whole-property Hotel Carbon Footprint per occupied room. Applies to the per-occupied-room calculation only — ignored when `square_meters` is provided.
* `"hotel_type"`: `hotel_type` is mutually exclusive with `stars`, `stars` is prioritized over `hotel_type`. Available values include: `airport_location`, `convention_hotel`, `extended_stay`, `full_service_nonresort`, `full_service_resort`, `hotel_average`, etc. Default value is `"hotel_average"`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
* **Default values**
* `"hotel_type": "hotel_average"`
### Sample API Response
```json
{
"carbon_quantity": 44475,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 44475,
"carbon_unit": "gram",
"external_reference": "string",
"type": "hotel",
"methodology": "HCMI"
}
]
}
```
## Bibliography
* Ricaurte, Eric. *Hotel Sustainability Benchmarking Index 2024: Carbon, Energy, and Water*. 2024
# Train
Train travel, often celebrated for its comparatively lower carbon footprint, still contributes to environmental emissions. From the energy source powering the locomotives to the infrastructure maintenance, every journey has its carbon tale.
**REM (Rail Emission Model)** is the operator- and country-aware methodology for train items on the Calculation API when you set `methodology` to **`REM`**. If you omit `methodology`, the API uses your client's configured train default. See [**Train: REM**](/api-calculations-request-response/travel/train/train-rem) for tiered factor resolution, distance and `route_coords` behavior, and auditable request fields (`departure_date`, ISO country codes, `energy_scope`, etc.).
Other national and framework methodologies (ADEME, DEFRA, US EPA, and others) are listed in the table of contents for this section.
With SQUAKE's precise carbon calculation tools, rail operators can detail these emissions with unwavering accuracy. Integrating SQUAKE ensures that train journeys aren't just scenic but also transparently green, allowing passengers to ride the rails with a clear environmental conscience.
# Train: ADEME 🇫🇷
## High‑Level Description
* ADEME (French Agency for Ecological Transition) provides a comprehensive methodology to assess the environmental impacts of train travel.
* Coverage spans the full lifecycle (vehicle and infrastructure production, operations, maintenance, and end‑of‑life).
* Key drivers include train type (high‑speed, mainline, local/express), traction/fuel (electricity vs. diesel), grid mix, and infrastructure allocation.
* Intended users: railway operators, policymakers, aggregators, and product teams who need transparent, audit‑ready train CO₂e estimates.
***
## Sample API Requests
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "train",
"external_reference": "test_2",
"origin": "BER",
"destination": "FRA",
"number_of_travelers": 3,
"train_type": "mainline",
"fuel_type": "diesel",
"methodology": "ADEME"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "train",
"external_reference": "test_2",
"origin": "BER",
"destination": "FRA",
"number_of_travelers": 3,
"train_type": "mainline",
"fuel_type": "diesel",
"methodology": "ADEME"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
## API Request Items
* `"type": "train"` **(required)**
* `"methodology": "ADEME"` **(required)**
* `"external_reference"`: A unique identifier linking results to the requested item. Max length: 128 chars.
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"`: Origin location (see **Origin/Destination Formats** below).
* `"destination"`: Destination location (see **Origin/Destination Formats** below).
* `"distance_in_km"`: If provided, this value is **prioritized** over `origin`/`destination`. If both are present, `distance_in_km` is used.
* `"train_type"`: One of `high_speed`, `mainline`, `local_express`. **Default:** `local_express`.
* `"fuel_type"`: One of `diesel`, `electricity`. **Default:** `diesel`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### Default Values
```json
{
"fuel_type": "diesel",
"train_type": "local_express",
"number_of_travelers": 1
}
```
***
## Origin/Destination Formats (Enriched)
SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:
* **Addresses:** Use the *Post* standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `"MUC"`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
**UIC and Provider Codes for Trains**
* UIC code is also a valid format for trains. If the value is not valid, the system will **fallback to general, non‑journey‑specific emission data**.
* When you want to use a UIC or provider code, use the following format:
* `:` (e.g., `sncf:FRAAA`)
* **Possible provider prefixes:**
* `uic`
* `uic8_sncf`
* `sncf`
* `sncf_tvs`
* `entur`
* `db`
* `busbud`
* `distribusion`
* `flixbus`
* `cff`
* `leoexpress`
* `obb`
* `trenitalia`
* `trenitalia_rtvt`
* `trenord`
* `ntv_rtiv`
* `ntv`
* `hkx`
* `renfe`
* `atoc`
* `benerail`
* `westbahn`
**Examples**
```jsonc
// Using UIC/provider code
{
"type": "train",
"methodology": "ADEME",
"origin": "db:8011160", // Berlin Hbf (example code structure)
"destination": "db:8000105", // Frankfurt (Main) Hbf (example code structure)
"number_of_travelers": 2
}
// Using UN/LOCODEs (for multimodal contexts)
{
"type": "train",
"methodology": "ADEME",
"origin": "DEBER", // Berlin (city code example)
"destination": "DEFRA", // Frankfurt (city code example)
"number_of_travelers": 1
}
// Using coordinates
{
"type": "train",
"methodology": "ADEME",
"origin": "+52.525,13.369",
"destination": "+50.110,8.682",
"number_of_travelers": 1
}
```
> **Notes**
>
> * If both `origin`/`destination` **and** `distance_in_km` are provided, `distance_in_km` is used for emissions.
> * Invalid, unsupported, or unresolvable location codes will trigger a **fallback** to generic (non‑journey‑specific) factors consistent with ADEME.
***
## Sample API Response
```json
{
"carbon_quantity": 6669,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 6669,
"carbon_unit": "gram",
"external_reference": "test_2",
"type": "train",
"methodology": "ADEME",
"distance": 435.0,
"distance_unit": "kilometer"
}
]
}
```
***
## Bibliography
* *GHG information for transport services* (June 2019). Ministère de la Transition Écologique et Solidaire. URL:
# Train: Base Empreinte 🇫🇷
## High-Level Description
Base Empreinte, managed by ADEME, is a comprehensive environmental impact database combining data from Base Carbone and Base IMPACTS. It supports environmental evaluations by offering multi-criteria data, including greenhouse gas (GHG) emissions and other environmental impacts.
Applied to train travel, Base Empreinte factors in key variables such as train type, location context (e.g., Corsica and Île‑de‑France), grid/fuel, and year of the factor, enabling accurate, audit‑ready emission calculations for stakeholders.
***
## Sample API Requests
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "train",
"methodology": "BASE-EMPREINTE",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "NCE",
"train_type": "tram",
"state": "Ile-de-France",
"country": "FR",
"year": "2021"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "train",
"methodology": "BASE-EMPREINTE",
"external_reference": "test_1",
"number_of_travelers": 1,
"origin": "FRA",
"destination": "NCE",
"train_type": "tram",
"state": "Ile-de-France",
"country": "FR",
"year": "2021"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
## API Request Items
* `"type": "train"` **(required)**
* `"methodology": "BASE-EMPREINTE"` **(required)**
* `"external_reference"`: A unique identifier linking results to the requested item. Max length: 128 chars.
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"`: Origin location (see **Origin/Destination Formats** below).
* `"destination"`: Destination location (see **Origin/Destination Formats** below).
* `"distance_in_km"`: If provided, this value is **prioritized** over `origin`/`destination`. If both are present, `distance_in_km` is used.
* `"train_type"`: One of `ter`, `tgv`, `intercity`, `metro`, `tram`, `trolleybus`, `main_line`. **Default:** `main_line` when only train type is passed.
* `"state"`: Supported regional specificity: `"Corsica"` or `"Ile-de-France"`. **Default:** `"Ile-de-France"`.
* `"country"`: ISO 3166‑1 alpha‑2 country code. **Default:** `"FR"`.
* `"year"`: Year of the factor. **Default:** latest available if not provided.
* `"city_type"`: Used when `state` not provided; one of `population_under_250000` (default) or `population_above_250000`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### Default Values
```json
{
"city_type": "population_under_250000",
"country": "FR",
"year": "latest_available",
"train_type": "main_line",
"number_of_travelers": 1
}
```
***
## Origin/Destination Formats (Enriched)
SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:
* **Addresses:** Use the *Post* standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `"MUC"`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
**UIC and Provider Codes for Trains**
* UIC code is also a valid format for trains. If the value is not valid, the system will **fallback to general, non‑journey‑specific emission data**.
* When you want to use a UIC or provider code, use the following format:
* `:` (e.g., `sncf:FRAAA`)
* **Possible provider prefixes:**
* `uic`
* `uic8_sncf`
* `sncf`
* `sncf_tvs`
* `entur`
* `db`
* `busbud`
* `distribusion`
* `flixbus`
* `cff`
* `leoexpress`
* `obb`
* `trenitalia`
* `trenitalia_rtvt`
* `trenord`
* `ntv_rtiv`
* `ntv`
* `hkx`
* `renfe`
* `atoc`
* `benerail`
* `westbahn`
**Examples**
```jsonc
// Using UIC/provider code
{
"type": "train",
"methodology": "BASE-EMPREINTE",
"origin": "db:8011160", // Berlin Hbf (example code structure)
"destination": "db:8000105", // Frankfurt (Main) Hbf (example code structure)
"number_of_travelers": 2
}
// Using UN/LOCODEs (for multimodal contexts)
{
"type": "train",
"methodology": "BASE-EMPREINTE",
"origin": "DEBER", // Berlin (city code example)
"destination": "DEFRA", // Frankfurt (city code example)
"number_of_travelers": 1
}
// Using coordinates
{
"type": "train",
"methodology": "BASE-EMPREINTE",
"origin": "+52.525,13.369",
"destination": "+50.110,8.682",
"number_of_travelers": 1
}
```
> **Notes**
>
> * If both `origin`/`destination` **and** `distance_in_km` are provided, `distance_in_km` is used for emissions.
> * Invalid, unsupported, or unresolvable location codes will trigger a **fallback** to generic (non‑journey‑specific) factors consistent with Base Empreinte/ADEME practice.
***
## Sample API Response
```json
{
"carbon_quantity": 4890,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 4890,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "train",
"methodology": "BASE-EMPREINTE",
"distance": 685.0,
"distance_unit": "kilometer"
}
]
}
```
***
## Bibliography
* ADEME. (2025). Base Empreinte - Données d’impacts environnementaux.
* ADEME. (2024). Base Carbone Methodological Guide.
* ADEME. (2023). Base IMPACTS & Rail emission factors — official ADEME documentation.
# Train: CO2-emissiefactoren 🇳🇱
## High-Level Description
CO2-emissiefactoren is a leading European reference for robust, harmonized CO₂ emission values across sectors, including rail. For train travel, it reflects operational energy, electricity mix, traction efficiency, and (where applicable) infrastructure impacts—supporting consistent, comparable, and decision-useful results.
> **Note on versions:** The factor set is published per year. Set `methodology_version` (a 4-digit year) to pin a version for reproducible results. On this endpoint, omitting it uses the **latest supported year** — train items carry no date, so the year is never inferred here. (On the [Travel Data API](/travel-data), where activities do carry dates, an omitted `methodology_version` is derived from the trip/activity start date instead.) A requested year without its own published set resolves to the most recent prior year (e.g. `2024` → `2023`), and a year before the earliest supported set (`2020`) returns a validation error. Supported years: **2020, 2021, 2023, 2025, 2026**.
***
## Sample API Requests
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "train",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"external_reference": "test",
"train_type": "international",
"fuel_type": "average",
"origin": "AMS",
"destination": "BER",
"number_of_travelers": 1,
"energy_scope": "ttw"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "train",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"external_reference": "test",
"train_type": "international",
"fuel_type": "average",
"origin": "AMS",
"destination": "BER",
"number_of_travelers": 1,
"energy_scope": "ttw"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
## API Request Items
* `"type": "train"` **(required)**
* `"methodology": "CO2-EMISSIEFACTOREN-NL"` **(required)**
* `"methodology_version"`: Factor year, one of `2020`, `2021`, `2023`, `2025`, `2026`, or `latest`. **Optional**. If omitted, the year is derived from the trip/activity start date, defaulting to the **latest supported year** when no date is available.
* `"external_reference"`: A unique identifier linking results to the requested item. Max length: 128 chars.
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"`: Origin location (see **Origin/Destination Formats** below).
* `"destination"`: Destination location (see **Origin/Destination Formats** below).
* `"distance_in_km"`: If provided, this value is **prioritized** over `origin`/`destination`. If both are present, `distance_in_km` is used.
* `"train_type"`: One of `average`, `international`. **Default:** `average`.
* `"fuel_type"`: One of `diesel`, `electricity`, `average`. **Default:** `average`.
* `"energy_scope"`: Well-to-wheel scope selector. One of `ttw` or `wtw`. **Default:** `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### Default Values
```json
{
"train_type": "average",
"fuel_type": "average",
"energy_scope": "wtw",
"number_of_travelers": 1,
"methodology_version": "latest"
}
```
> Note: If your integration assumes `train_type: intercity` as a product-level alias, map it to the dataset’s available categories (`average` or `international`) according to your business rules.
***
## Origin/Destination Formats (Enriched)
SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:
* **Addresses:** Use the *Post* standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `"MUC"`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
**UIC and Provider Codes for Trains**
* UIC code is also a valid format for trains. If the value is not valid, the system will **fallback to general, non-journey-specific emission data**.
* When you want to use a UIC or provider code, use the following format:
* `:` (e.g., `sncf:FRAAA`)
* **Possible provider prefixes:**
* `uic`
* `uic8_sncf`
* `sncf`
* `sncf_tvs`
* `entur`
* `db`
* `busbud`
* `distribusion`
* `flixbus`
* `cff`
* `leoexpress`
* `obb`
* `trenitalia`
* `trenitalia_rtvt`
* `trenord`
* `ntv_rtiv`
* `ntv`
* `hkx`
* `renfe`
* `atoc`
* `benerail`
* `westbahn`
**Examples**
```jsonc
// Using UIC/provider code
{
"type": "train",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"origin": "db:8011160", // Berlin Hbf (example code structure)
"destination": "db:8000105", // Frankfurt (Main) Hbf (example code structure)
"number_of_travelers": 1,
"energy_scope": "wtw"
}
// Using UN/LOCODEs (for multimodal contexts)
{
"type": "train",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"origin": "NLAMS", // Amsterdam (city/port code example)
"destination": "DEBER", // Berlin (city code example)
"number_of_travelers": 1
}
// Using coordinates
{
"type": "train",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"origin": "+52.379,4.900", // Amsterdam
"destination": "+52.525,13.369",// Berlin
"number_of_travelers": 1
}
```
> **Notes**
>
> * If both `origin`/`destination` **and** `distance_in_km` are provided, `distance_in_km` is used for emissions.
> * Invalid, unsupported, or unresolvable location codes will trigger a **fallback** to generic (non-journey-specific) factors consistent with the CO2‑emissiefactoren methodology.
***
## Sample API Response
```json
{
"carbon_quantity": 10132,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 10132,
"carbon_unit": "gram",
"external_reference": "test",
"type": "train",
"methodology": "CO2-EMISSIEFACTOREN-NL",
"distance": 596.0,
"distance_unit": "kilometer"
}
]
}
```
***
## Bibliography
* Lijst emissiefactoren (2025). CO₂-emissiefactoren.
* Milieu Centraal (n.a.).
# Train: DEFRA 🇬🇧
💡 **High-Level Description:**
DEFRA (Department for Environment, Food & Rural Affairs) provides essential conversion factors and guidelines for calculating greenhouse gas (GHG) emissions across various sectors, including passenger rail services. As one of the main references for emissions reporting in the UK, DEFRA’s methodology ensures consistency, transparency, and accuracy when assessing the environmental impact of train travel.
The methodology focuses on direct emissions from train fuel combustion and indirect emissions associated with electricity consumption. DEFRA distinguishes between electric and diesel-powered trains, accounting for varying levels of emissions based on fuel type, train type (e.g., national, international, light rail), and distance traveled. DEFRA's framework is widely used in corporate GHG reporting, providing essential data for understanding the carbon impact of train travel and supporting efforts to reduce emissions.
**Versioning:** Add `methodology_version` to pin a specific DEFRA **Conversion Factors** year (e.g., `"2024"`). If omitted, SQUAKE **uses the latest supported year**.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "train",
"external_reference": "test_1",
"origin": "BER",
"destination": "FRA",
"number_of_travelers": 3,
"train_type": "national",
"methodology": "DEFRA",
"energy_scope": "ttw",
"methodology_version": "2024"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "train",
"external_reference": "test_1",
"origin": "BER",
"destination": "FRA",
"number_of_travelers": 3,
"train_type": "national",
"methodology": "DEFRA",
"energy_scope": "ttw",
"methodology_version": "2024"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### **API Request Items**
* `"type": "train"` **(required)**
* `"methodology": "DEFRA"` **(required)**
* `"methodology_version"`: DEFRA **Conversion Factors** year (e.g., `"2024"`). **Optional**; if omitted → **latest supported year**.
* `"external_reference"`: Unique identifier to link the result (max 128 chars).
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"` / `"destination"`: Flexible formats (postal, IATA/ICAO `^[A-Z]{3,4}$`, UN/LOCODE `^[A-Z]{2}\W?[A-Z2-9]{3}$`, or `"lat,lon"`). Distance is auto-resolved.
* `"distance_in_km"`: If provided, **overrides** origin/destination.
* `"train_type"`: Supported categories (per DEFRA): `"national"`, `"international"`, `"light"`, `"tram"`, `"underground"`.
* `"energy_scope"`: `"wtw"` (**default**) or `"ttw"`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
## Origin/Destination Formats (Enriched)
SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:
* **Addresses:** Use the *Post* standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `"MUC"`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
**UIC and Provider Codes for Trains**
* UIC code is also a valid format for trains. If the value is not valid, the system will **fallback to general, non-journey-specific emission data**.
* When you want to use a UIC or provider code, use the following format:
* `:` (e.g., `sncf:FRAAA`)
* **Possible provider prefixes:**
* `uic`
* `uic8_sncf`
* `sncf`
* `sncf_tvs`
* `entur`
* `db`
* `busbud`
* `distribusion`
* `flixbus`
* `cff`
* `leoexpress`
* `obb`
* `trenitalia`
* `trenitalia_rtvt`
* `trenord`
* `ntv_rtiv`
* `ntv`
* `hkx`
* `renfe`
* `atoc`
* `benerail`
* `westbahn`
**Examples**
```jsonc
// Using UIC/provider code
{
"type": "train",
"methodology": "DEFRA",
"origin": "atoc:1072", // Example UK station code structure
"destination": "atoc:5935",
"number_of_travelers": 1,
"energy_scope": "wtw",
"methodology_version": "2024"
}
// Using UN/LOCODEs (for multimodal contexts)
{
"type": "train",
"methodology": "DEFRA",
"origin": "GBLON", // London
"destination": "GBMAN", // Manchester
"number_of_travelers": 1
}
// Using coordinates
{
"type": "train",
"methodology": "DEFRA",
"origin": "+51.503,-0.125", // London
"destination": "+53.480,-2.242",// Manchester
"number_of_travelers": 1
}
```
> **Notes**
>
> * If both `origin`/`destination` **and** `distance_in_km` are provided, `distance_in_km` is used for emissions.
> * Invalid, unsupported, or unresolvable location codes will trigger a **fallback** to generic (non-journey-specific) factors consistent with the DEFRA methodology.
***
### **Default Values**
* `"train_type": "national"`
* `"energy_scope": "wtw"`
* `"methodology_version"`: **latest supported DEFRA year**
***
### **Sample API Response**
```json
{
"carbon_quantity": 6669,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 6669,
"carbon_unit": "gram",
"external_reference": "test_2",
"type": "train",
"methodology": "DEFRA",
"methodology_version": "2024",
"distance": 435.0,
"distance_unit": "kilometer"
}
]
}
```
***
### **Versions**
* **Behavior:** If `methodology_version` is omitted, SQUAKE automatically applies the **latest supported** DEFRA Conversion Factors year. Pin a year for reproducibility and audit readiness.
***
### **Bibliography**
* UK Government — **Greenhouse gas emissions: Research & statistics**:
* DEFRA (2024). **Government Greenhouse Gas Conversion Factors for Company Reporting** (Rail factors).
* UK Office of Rail and Road. **National Rail Trends**.
* Eurostar. **GHG Methodology Report**.
# Train: EPA 🇺🇸
💡 **High-Level Description**
The **US EPA GHG Emission Factors Hub** provides passenger-rail emission factors used for corporate greenhouse gas (GHG) accounting in the United States. For trains, factors are expressed as **gCO₂e per passenger-kilometer** and include **CO₂, CH₄, and N₂O** aggregated using the EPA’s 100-year GWPs for the given Hub year. In this implementation:
* Units: **gCO₂e/pax-km**
* Scope: **well-to-wheel (WTW)** representation of emissions reflected in EPA’s factors
* Coverage: **intercity** (national average & route-specific), **commuter rail**, and **transit rail**
> **Note on versions:** If `methodology_version` is omitted, SQUAKE will **always use the latest supported EPA Hub year**. Pinning is recommended for reproducibility.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "train",
"external_reference": "test_1",
"distance_in_km": 500,
"number_of_travelers": 1,
"methodology": "US-EPA",
"train_type": "intercity_national_average"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "train",
"external_reference": "test_1",
"distance_in_km": 500,
"number_of_travelers": 1,
"methodology": "US-EPA",
"train_type": "intercity_national_average"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### **API Request Items**
* `"type": "train"` **(required)**
* `"methodology": "US-EPA"` **(required)**
* `"methodology_version"`: EPA Hub year (e.g., `"2023"`). **Optional**. If omitted, the calculation **defaults to the latest supported year**.
* `"external_reference"`: Your unique identifier for correlating responses. Max length 128 chars.
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"distance_in_km"`: **Preferred** distance input. If both `distance_in_km` and `origin`/`destination` are given, `distance_in_km` is used.
* `"origin"` and `"destination"` (optional): If provided, SQUAKE will resolve the rail distance. Accepts IATA/ICAO/UNLOCODE/postal formats or `"lat,lon"` (e.g., `"+40.712,-74.006"`).\
*Note: For EPA factors, the **train type** should match U.S. service classes (see below).*
* `"train_type"`: **Supported**
* `"intercity_northeast_corridor"`
* `"intercity_other_routes"`
* `"intercity_national_average"`
* `"commuter_rail"`
* `"transit_rail"`
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
**Defaults**
* `"train_type": "intercity_national_average"`
* `"number_of_travelers": 1"`
* If `"methodology_version"` is omitted → **latest supported EPA Hub year**.
***
## Origin/Destination Formats (Enriched)
SQUAKE will try to resolve the `origin`/`destination` regardless of its format. Ideally:
* **Addresses:** Use the *Post* standard.
* **Airports:** Use IATA/ICAO code (regex: `^[A-Z]{3,4}$`, e.g., `"MUC"`).
* **Ports/Trade locations:** Use UN/LOCODE (regex: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`).
* **Coordinates:** Pass latitude/longitude (regex: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
**UIC and Provider Codes for Trains**
* UIC code is also a valid format for trains. If the value is not valid, the system will **fallback to general, non-journey-specific emission data**.
* When you want to use a UIC or provider code, use the following format:
* `:` (e.g., `atoc:1072` or `amtrak:NYP` as illustrative code styles)
* **Possible provider prefixes:**
* `uic`
* `uic8_sncf`
* `sncf`
* `sncf_tvs`
* `entur`
* `db`
* `busbud`
* `distribusion`
* `flixbus`
* `cff`
* `leoexpress`
* `obb`
* `trenitalia`
* `trenitalia_rtvt`
* `trenord`
* `ntv_rtiv`
* `ntv`
* `hkx`
* `renfe`
* `atoc`
* `benerail`
* `westbahn`
**Examples**
```jsonc
// Using a provider code (illustrative; US context)
{
"type": "train",
"methodology": "US-EPA",
"origin": "atoc:1072", // Example code structure
"destination": "atoc:5935",
"number_of_travelers": 1,
"train_type": "intercity_national_average"
}
// Using UN/LOCODEs (for multimodal contexts)
{
"type": "train",
"methodology": "US-EPA",
"origin": "USNYC", // New York City
"destination": "USWAS", // Washington, DC
"number_of_travelers": 1,
"train_type": "intercity_northeast_corridor"
}
// Using coordinates
{
"type": "train",
"methodology": "US-EPA",
"origin": "+40.750,-73.993", // Near NYC Penn Station
"destination": "+38.897,-77.007",// Washington, DC
"number_of_travelers": 1,
"train_type": "intercity_northeast_corridor"
}
```
> **Notes**
>
> * If both `origin`/`destination` **and** `distance_in_km` are provided, `distance_in_km` is used for emissions.
> * Invalid, unsupported, or unresolvable location codes will trigger a **fallback** to generic (non-journey-specific) factors consistent with the US-EPA methodology.
***
### **Computation**
Let **EF** be the factor in gCO₂e/pax-km for the chosen `train_type` and `methodology_version` (or latest if omitted).
```
total_gCO2e = EF × distance_in_km × number_of_travelers
```
All outputs are returned in **grams** by default.
***
### **Sample API Response**
```json
{
"carbon_quantity": 18127.337,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 18127.337,
"carbon_unit": "gram",
"external_reference": "test_case_1",
"type": "train",
"methodology": "US-EPA",
"distance": 500.0,
"distance_unit": "kilometer",
"train_type": "intercity_northeast_corridor"
}
]
}
```
***
### **Bibliography**
* **US EPA.** *GHG Emission Factors Hub* (Passenger Rail).
# Train: Green Travel Pledge
💡 **High‑Level Description**
**Green Travel Pledge (GTP)** is an industry initiative led by the UK **Rail Delivery Group (RDG)** providing recognised, route‑level carbon data for rail journeys in Great Britain. Under the umbrella **Green Travel Data (GTD)** programme, RDG publishes per‑journey and per‑passenger emissions so businesses can compare rail with car and air and drive modal shift.
GTP focuses on **per‑passenger CO₂e** for specific **origin–destination** pairs and, where available, **seat class**. When a journey‑specific figure is not provided, the dataset offers fallback factors per passenger‑kilometre. SQUAKE implements both layers with deterministic fallbacks and preserves comparison values for **diesel car, plug‑in hybrid, battery electric car, and air** for auditability.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "train",
"external_reference": "test_1",
"origin": "GRF",
"destination": "MBR",
"number_of_travelers": 1,
"seat_type": "second_class",
"methodology": "GREEN-TRAVEL-PLEDGE",
"departure_date": "2025-05-03"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "train",
"external_reference": "test_1",
"origin": "GRF",
"destination": "MBR",
"number_of_travelers": 1,
"seat_type": "second_class",
"methodology": "GREEN-TRAVEL-PLEDGE",
"departure_date": "2025-05-03"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
***
### **API Request Items**
* `"type"`: `"train"` **(required)**
* `"methodology"`: `"GREEN-TRAVEL-PLEDGE"` **(required)**
* `"external_reference"`: Correlates request/response (max 128 chars).
* `"number_of_travelers"`: Minimum `1`. **Default:** `1`.
* `"origin"` / `"destination"`: Stations per GTD (GB rail). Standard resolvers (CRS/3‑letter, TIPLOC, name) supported.
* `"departure_date"`: ISO date `YYYY-MM-DD`. Used to select the **latest dataset published on or before** this date. If omitted, SQUAKE uses the **latest available dataset** at calculation time (captured in metadata as `dataset_date`).
* `"distance_in_km"` (optional): If provided, used **only for fallback** when per‑journey emissions are not available and per‑pax‑km factors must be applied.
* `"seat_type"` (optional): One of `"first_class"`, `"second_class"`, `"average"` (**default:** `"average"`). See mapping below.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
***
### **Seat Type Mapping**
* Client → GTP:
* `"second_class"` → `"standard"`
* `"first_class"` → `"first"`
* `"average"` → use dataset `"average"` (where available) or computed average if class values are missing.
**Zero‑value guardrails**
* If the class value (**standard/first**) is present but equals `0`, SQUAKE uses the **`average`** value for that journey.
* If class **and** average are missing or zero, SQUAKE enters **fallback mode** (see below).
***
### **Calculation & Fallbacks**
1. **Primary (per‑journey CSV)** – `gtd-emissions-output-by-journey.csv`
* Use the **exact O–D** row for the specified `departure_date` dataset.
* Choose class‑specific value (`first` or `standard`) or `average` per the mapping/guards above.
* Multiply by `number_of_travelers`. Result is **grams CO₂e** if dataset is already per journey; otherwise convert as per dataset units.
2. **Fallback (per‑passenger‑km CSV)** – `gtd-emissions-output-by-passenger.csv`
* Take factor **kgCO₂e/pax/km**; compute:
```
grams = factor_kg_per_pax_km × distance_in_km × number_of_travelers × 1000
```
* `distance_in_km` is required for fallback. If not provided, SQUAKE attempts to resolve rail distance; on failure, returns `distance_required` error.
**Comparison Modes (saved for audit)**
* Alongside train emissions, SQUAKE stores comparison values (if provided by GTP dataset) for:
* **Diesel Car**, **Plug‑in Hybrid Electric Car**, **Battery Electric Car**, **Air**.
* If a comparison value equals `0`, SQUAKE records `"N/A"` meaning **Not Comparable**.
***
### **Default Values**
* `"seat_type": "average"`
* Dataset selection: **latest published on/ before `departure_date`**; otherwise **latest available** (metadata includes `dataset_date`).
***
### **Sample API Response**
```json
{
"carbon_quantity": 1580,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 1580,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "train",
"methodology": "GREEN-TRAVEL-PLEDGE",
"origin": "GRF",
"destination": "MBR",
"seat_type": "second_class",
"dataset_date": "2025-05-01",
"data_source": "journey",
"distance": 0.0,
"distance_unit": "kilometer",
"metadata": {
"comparison": {
"diesel_car_g": 4860,
"phev_car_g": 3140,
"bev_car_g": 1430,
"air_g": "N/A"
}
}
}
]
}
```
***
### **Versions / Dataset Updates**
* GTP datasets are periodically refreshed. SQUAKE selects the **latest dataset at or before `departure_date`** (or latest available if `departure_date` is omitted) and returns `dataset_date` for traceability.
***
### **Bibliography**
* Rail Delivery Group — **Green Travel Data / Green Travel Pledge** (programme overview & calculator).\
# Train: REM
Documentation on this page is aligned to **REM methodology v2.6** (integration and Calculation API payloads). Use **`"methodology": "REM"`** in all new integrations.
Set `methodology` to **`REM`** to use REM. If you omit `methodology` on a train item, the API uses your client's configured train default.
***
## Overview
REM is an operator- and country-aware rail methodology. It selects an emission factor (grams CO₂e per passenger-kilometre) using a **deterministic tiered resolver**, then multiplies by distance and passenger count.
Supplying **`operator_name`**, ISO **country codes**, **`departure_date`**, and **`energy_scope`** when you have them improves tier matching and makes results easier to audit.
***
## Factor resolution (tiers)
REM applies this order:
1. **Tier 1 — Operator-reported** Used when `operator_name` matches operator-specific factors for the requested `energy_scope`, `train_type`, and (when needed) `fuel_type` / year.
2. **Tier 2 — Operator-reported mix** Used when `operator_name` matches operator-specific energy mix for the requested `energy_scope`, `train_type`, and (when needed) `fuel_type` / year.
3. **Tier 3 — Country-published** Uses country-level methodology data when **Tier 1** and **Tier 2** do not apply and a country context is available (see **Country context** below).
4. **Tier 4 — Activity-based** Uses fuel, traction mix, and electricity carbon intensity data for the country/region when Tier 3 does not yield a factor.
5. **Tier 5 — Global constant** Well-to-wheel global rail averages (IEA-based constants), with a pre/post cut-off driven by `departure_date` when present.
**Country context for Tiers 3–4:** The resolver uses **`origin_country`** if set, otherwise **`destination_country`** (both optional). Values should be **ISO 3166-1 alpha-2** (e.g. `DE`, `SE`). The API accepts other resolvable country inputs and normalizes to alpha-2 where possible (e.g. `UK` → `GB`). If neither country field is available, Tier 1 and Tier 2 may still apply; otherwise resolution falls through toward **Tier 5**.
***
## Distance handling
You must provide **one** of the following (after validation):
* **`origin` and `destination`** (resolved to a route distance), or
* **`distance_in_km`** (positive number), or
* **`route_coords`**: an array of at least **two** `[longitude, latitude]` pairs (WGS84). Longitude must be in **\[-180, 180]**, latitude in **\[-90, 90]**.
**Precedence:** If **`distance_in_km`** is set together with `origin` / `destination`, **`distance_in_km`** is used for the calculation distance.
**Corrections:**
* If you send **`route_coords`**, the API computes a **border-aware** path distance (per-country segments, train-type **detour factor** from REM data). That total becomes the distance used for emissions; **no additional "air distance" correction** is applied on top.
* If you send **`distance_in_km`** **without** `route_coords`, REM still applies the **air-distance correction** used for straight-line or user-supplied distances (so driven distance is consistent with the methodology).
* For **audit / debugging**, expanded item metadata may include a **`border_distance_breakdown`** when `route_coords` were used (sequential segments and totals per ISO alpha-3 country). If some segments cannot be attributed to a country, a warning may be present.
***
### **Sample API Requests**
#### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "train",
"external_reference": "test_1",
"origin": "Stockholm",
"destination": "Malmo",
"number_of_travelers": 1,
"train_type": "high_speed",
"seat_type": "second_class",
"fuel_type": "electricity",
"operator_name": "sj",
"methodology": "REM",
"departure_date": "2025-06-15",
"origin_country": "SE",
"destination_country": "SE",
"energy_scope": "wtw"
}
]
}
```
#### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "train",
"external_reference": "test_1",
"origin": "Stockholm",
"destination": "Malmo",
"number_of_travelers": 1,
"train_type": "high_speed",
"seat_type": "second_class",
"fuel_type": "electricity",
"operator_name": "sj",
"methodology": "REM",
"departure_date": "2025-06-15",
"origin_country": "SE",
"destination_country": "SE",
"energy_scope": "wtw"
}
]
}
```
> **Note:** `audit_for` is optional. Provide it when calculating on behalf of a specific Auditable entity; otherwise omit.
#### C. Route path (`route_coords`) without origin/destination
When `route_coords` is valid, `origin` and `destination` are not required for distance validation.
```json
{
"expand": ["items"],
"items": [
{
"type": "train",
"methodology": "REM",
"external_reference": "route_coords_1",
"number_of_travelers": 1,
"train_type": "high_speed",
"route_coords": [
[13.405, 52.52],
[10.0, 51.0],
[8.682, 50.11]
],
"operator_name": "db",
"energy_scope": "wtw"
}
]
}
```
***
### **API request fields**
* **`type`**: `"train"` (required).
* **`methodology`**: `"REM"`. If omitted, the API uses your client's configured train default.
* **`external_reference`**: Unique id for the item in the request (helps map results to inputs). Max length **128** characters.
* **`number_of_travelers`**: Integer ≥ `1`. Default **`1`**.
* **`origin`**, **`destination`**: Location strings as in other train methodologies (addresses, IATA/ICAO, UN/LOCODE, coordinates, UIC/provider codes — see **Origin/destination formats** below). Required unless you supply **`distance_in_km`** or valid **`route_coords`**.
* **`distance_in_km`**: Optional. If provided together with `origin` / `destination`, this value wins. Subject to REM **air-distance correction** unless `route_coords` are used.
* **`route_coords`**: Optional. Array of `[lon, lat]` pairs; minimum **2** points. Each pair must have exactly two numbers. Used for border-aware distance and detour factor.
* **`train_type`**: One of: **`average`**, **`high_speed`**, **`intercity`**, **`regional`**, **`long_distance`**, **`commuter`**, **`tram`**, **`metro`**, **`light_rail`**, **`urban_rail`**. API default when omitted: **`average`**.
* **`fuel_type`**: **`diesel`**, **`electricity`**, **`hvo`**, **`hydrogen`**. Default **`diesel`**. Used for **Tier 1** and **Tier 2** disambiguation when an operator has multiple fuel rows, and for **Tier 3** and **Tier 4** modelling where applicable.
* **`seat_type`**: **`average`**, **`first_class`**, or **`second_class`**. Default **`average`**.
* **`operator_name`**: Optional; enables **Tier 1** or **Tier 2** when the operator exists in the REM operator database. Contact for the full currently supported list of operators.
* **`departure_date`**: Optional. **ISO 8601 calendar date** only: **`YYYY-MM-DD`** (date-only, not a full timestamp). Used to select year-matched factors. If invalid, the API returns: **`Departure date '' is not a valid ISO-8601 date.`**
* **`origin_country`**, **`destination_country`**: Optional. **ISO 3166-1 alpha-2** recommended (e.g. `DE`, `FR`). Other resolvable country strings may be accepted and normalized to alpha-2. Invalid codes return a parameter error. For country-based tiers, **`origin_country`** is preferred over **`destination_country`** when both are set.
* **`energy_scope`**: **`wtw`** (well-to-wheel, default) or **`ttw`** (tank-to-wheel). Invalid values return an error listing allowed scopes.
* **`audit`**: Optional boolean for immutable audit records (feature must be enabled for your account).
***
## Origin/destination formats (enriched)
We will try to resolve `origin` / `destination` regardless of format. Ideally:
* **Addresses:** Post/standard postal format.
* **Airports:** IATA/ICAO (`^[A-Z]{3,4}$`, e.g. `MUC`).
* **Ports / trade:** UN/LOCODE (`^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g. `DEHAM`).
* **Coordinates:** `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$` (e.g. `"+40.712,-74.006"`).
**UIC and provider codes**
* Invalid or unsupported codes may trigger **fallback** to more generic factors (non-journey-specific).
* Format: `:` (e.g. `sncf:FRAAA`).
* **Possible provider prefixes:** `uic`, `uic8_sncf`, `sncf`, `sncf_tvs`, `entur`, `db`, `busbud`, `distribusion`, `flixbus`, `cff`, `leoexpress`, `obb`, `trenitalia`, `trenitalia_rtvt`, `trenord`, `ntv_rtiv`, `ntv`, `hkx`, `renfe`, `atoc`, `benerail`, `westbahn`.
**Examples**
```jsonc
// UIC/provider (illustrative)
{
"type": "train",
"methodology": "REM",
"origin": "entur:7400001",
"destination": "entur:7400046",
"operator_name": "sj",
"number_of_travelers": 1
}
// UN/LOCODE
{
"type": "train",
"methodology": "REM",
"origin": "SESTO",
"destination": "SEMMA",
"number_of_travelers": 1
}
// Coordinates
{
"type": "train",
"methodology": "REM",
"origin": "+59.330,18.058",
"destination": "+55.605,13.003",
"number_of_travelers": 1
}
```
> **Notes**
>
> * If both `origin`/`destination` and `distance_in_km` are provided, `distance_in_km` is used.
> * Unresolvable locations produce validation errors or methodology fallbacks as described for train generally.
***
### **Sample API response**
When you expand **`items`**, each train item may include **`algorithm_specifics`** describing the resolved REM tier and matched metadata (for example `tier`, `energy_scope`, `gco2e_per_pax_km`, `year_matched`, `country_matched`, `operator_matched`, `source_links`, and resolver `details`). Exact shape follows the live API.
```json
{
"carbon_quantity": 261,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 261,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "train",
"methodology": "REM",
"distance": 616.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"tier": 1,
"energy_scope": "wtw",
"gco2e_per_pax_km": "0.42",
"year_matched": 2024,
"country_matched": "se",
"operator_matched": "sj",
"source_links": [],
"methodology": "operator_reported"
}
}
]
}
```
> The numeric / string formatting of `algorithm_specifics` fields matches the production API; treat `gco2e_per_pax_km` as a decimal string or number per response schema.
***
### **White Paper**
* "Rail Emission Model" *SQUAKE*, [ourworldindata.org/travel-carbon-footprint.](https://www.squake.earth/resources/rail-emission-model-whitepaper)
# Logistics
The logistics sector plays a crucial role in the movement of goods and materials worldwide. However, the transportation and delivery of products often come with a significant carbon footprint. Whether it's road freight, shipping, or air cargo, logistics activities contribute to global greenhouse gas emissions, making it essential to calculate and mitigate their impact. By understanding the emissions produced by various logistics activities, companies can make informed decisions to improve their sustainability and reduce their environmental impact.
Calculating the carbon emissions for logistics activities requires considering factors such as the type of transportation, distance traveled, and fuel type. Accurate measurement enables businesses to identify carbon reduction opportunities, optimize their supply chain, and contribute to global carbon reduction efforts.
## Perform a Calculation
### POST /v2/calculations
> Bearer auth
The calculations endpoint can calculate carbon emissions for one or multiple activities. The carbon footprint of your logistics operations, such as multiple freight journeys or combined land and sea shipments, can be computed all at once by passing all relevant activities in the "items" array. Include the string literal "items" in the "expand" array to retrieve values for each item separately in addition to the total carbon quantity.
This is a low-latency endpoint. SQUAKE does not provide you with a unique identifier for any calculation results. You must quote a price on the pricing endpoint to purchase compensation for your carbon emissions.
Some data sets are extensive and thus documented separately here.
### application/json
**Body**
* `expand` array\[string]: If you choose to expand on e.g., "items", SQUAKE returns emissions for each item separately (in addition to a total value).
* Value is `items`.
* `carbon_unit` string: SQUAKE uses The International System of Units (SI), commonly referred to as "metric system".
* Values are `tonne`, `kilogram`, or `gram`.
* `distance_unit` string: SQUAKE uses common distance units.
* Values are `meter`, `kilometer`, `feet`, `mile`, or `nautical_mile`. Default value is `kilometer`.
## Generic API Request Sample:
```json
{
"expand": [
"items"
],
"carbon_unit": "tonne",
"distance_unit": "kilometer",
"items": [
{
"type": "road_freight",
"external_reference": "Truck",
"origin": "Magdeburg, Germany",
"destination": "DEHAM",
"weight_in_tonnes": 0.75,
"fuel_type": "diesel",
"energy_scope": "wtw",
"truck_type": "rigid_truck_under_26_gvw",
"temperature_controlled_freight": true,
"methodology": "GLEC"
},
{
"type": "logistics_site",
"external_reference": "Hub",
"weight_in_tonnes": 0.75,
"logistics_site_type": "transhipment_site",
"methodology": "GLEC"
},
{
"type": "sea_freight",
"external_reference": "Sea",
"origin": "DEHAM",
"destination": "NLAMS",
"weight_in_tonnes": 0.75,
"cargo_type": "dry",
"energy_scope": "wtw",
"methodology": "CLEAN-CARGO"
},
{
"type": "logistics_site",
"external_reference": "Hub",
"weight_in_tonnes": 0.75,
"logistics_site_type": "storage_and_transhipment",
"methodology": "GLEC"
},
{
"type": "air_freight",
"external_reference": "Air",
"origin": "AMS",
"destination": "JFK",
"weight_in_tonnes": 0.75,
"plane_type": "belly_freighter",
"energy_scope": "wtw",
"methodology": "GLEC"
},
{
"type": "logistics_site",
"external_reference": "Hub",
"weight_in_tonnes": 0.75,
"logistics_site_type": "warehouse",
"methodology": "GLEC"
},
{
"type": "road_freight",
"external_reference": "Truck",
"origin": "JFK",
"destination": "Scranton, United States",
"weight_in_tonnes": 0.75,
"fuel_type": "diesel",
"energy_scope": "wtw",
"truck_type": "van_under_3.5_t",
"temperature_controlled_freight": true,
"methodology": "GLEC"
}
]
}
```
## Generic API Response Sample:
```json
{
"carbon_quantity": 4.570352,
"carbon_unit": "tonne",
"items": [
{
"carbon_quantity": 0.026645,
"carbon_unit": "tonne",
"external_reference": "Truck",
"type": "road_freight",
"methodology": "GLEC",
"distance": 244.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 26645,
"co2e_emissions_wtw_in_g": 26645,
"co2e_per_tonne_km_in_g": 130,
"tonne_km": 183,
"reporting_year": 2024,
"transportation_mode": "road_transportation"
}
}
},
{
"carbon_quantity": 0.00165,
"carbon_unit": "tonne",
"external_reference": "Hub",
"type": "logistics_site",
"methodology": "GLEC",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 1650.0,
"co2e_per_tonne_in_g": 2200,
"reporting_year": 2024,
"transportation_mode": "logistics_site"
}
}
},
{
"carbon_quantity": 0.004885,
"carbon_unit": "tonne",
"external_reference": "Sea",
"type": "sea_freight",
"methodology": "CLEAN-CARGO",
"distance": 368.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "clean_cargo",
"data": {
"co2e_in_g": 4885,
"co2e_emissions_wtw_in_g": 4885,
"co2e_per_tonne_km_in_g": 17.7,
"tonne_km": 276,
"reporting_year": 2024,
"transportation_mode": "sea_transportation"
}
}
},
{
"carbon_quantity": 0.003,
"carbon_unit": "tonne",
"external_reference": "Hub",
"type": "logistics_site",
"methodology": "GLEC",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 3000.0,
"co2e_per_tonne_in_g": 4000,
"reporting_year": 2024,
"transportation_mode": "logistics_site"
}
}
},
{
"carbon_quantity": 4.353479,
"carbon_unit": "tonne",
"external_reference": "Air",
"type": "air_freight",
"methodology": "GLEC",
"distance": 5978.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 4353479,
"co2e_emissions_wtw_in_g": 4353479,
"co2e_per_tonne_km_in_g": 971,
"tonne_km": 4484,
"reporting_year": 2024,
"transportation_mode": "air_transportation"
}
}
},
{
"carbon_quantity": 0.02475,
"carbon_unit": "tonne",
"external_reference": "Hub",
"type": "logistics_site",
"methodology": "GLEC",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 24750.0,
"co2e_per_tonne_in_g": 33000,
"reporting_year": 2024,
"transportation_mode": "logistics_site"
}
}
},
{
"carbon_quantity": 0.155943,
"carbon_unit": "tonne",
"external_reference": "Truck",
"type": "road_freight",
"methodology": "GLEC",
"distance": 228.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 155943,
"co2e_emissions_wtw_in_g": 155943,
"co2e_per_tonne_km_in_g": 793,
"tonne_km": 171,
"reporting_year": 2024,
"transportation_mode": "road_transportation"
}
}
}
]
}
```
# Air Freight
The air freight sector, indispensable for global trade, is a significant contributor to aviation's carbon emissions. From transcontinental shipments to regional deliveries, each cargo flight has an environmental impact. As global commerce escalates, the industry's carbon impact is more scrutinized, prompting a shift towards more sustainable logistics.
SQUAKE rises to this challenge, providing air freight companies with precise carbon emission calculations for each shipment. By integrating SQUAKE's solutions, carriers can display transparent emission data and offer automated compensation opportunities. This not only assures eco-conscious clients of a company's dedication to sustainability but also steers the air freight sector towards a more sustainable trajectory.
# Air Freight: DIN EN 16258
💡 **High-Level Description:**
The DIN EN 16258 standard, initiated by the European Committee for Standardization, offers a robust methodology for calculating transport services' energy consumption and greenhouse gas emissions, including the air freight sector. As global trade has exponentially grown, so has the urgency to standardize and mitigate the environmental impact of transporting goods. DIN EN 16258 is tailored to address this by introducing a comprehensive method that considers various aspects like aircraft type, fuel consumption, flight altitude, and cargo type.
More than just a calculation tool, the DIN EN 16258 standard provides a framework for companies to report their emissions transparently. Ensuring a uniform measure allows for comparison across the industry, incentivizing companies to optimize their operations and reduce their carbon emissions. As European countries push for greener logistics, adhering to the DIN EN 16258 standard signifies the commitment to sustainable practices and positions companies at the forefront of an eco-conscious transition.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "air_freight",
"external_reference": "test_1",
"origin": "MIL",
"destination": "HAM",
"weight_in_tonnes": 5,
"plane_type": "freighter",
"energy_scope": "wtw",
"methodology": "DIN-EN-16258"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "air_freight",
"external_reference": "test_1",
"origin": "MIL",
"destination": "HAM",
"weight_in_tonnes": 5,
"plane_type": "freighter",
"energy_scope": "wtw",
"methodology": "DIN-EN-16258"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"air_freight"` (required)
* `"methodology"`: `"DIN-EN-16258"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"plane_type"`: Values are `belly_freighter` and `freighter`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"plane_type": "belly_freighter"`
* `"energy_scope": "wtw"`
### **Sample API Response**
```json
{
"carbon_quantity": 2040166,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 2040166,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "air_freight",
"methodology": "DIN-EN-16258",
"distance": 981.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "DIN-EN-16258",
"data": {
"energy_factor_ttw_in_MJ": 24,
"energy_factor_wtw_in_MJ": 28,
"ghg_emissions_ttw_in_g": 1672095,
"ghg_emissions_wtw_in_g": 2040166
}
}
}
]
}
```
## **Bibliography**
* IATA Carbon Offset Program: Frequently Asked Questions (2022, April 19). IATA. Retrieved from
* IATA Recommended Practice -RP 1726 (n.d.). IATA. Retrieved from .
* IATA Recommended Practice 1678 (2014, March 9). IATA. Retrieved from
* Method for Calculating and Declaring Energy Consumption (2013, March). DIN EN 16258.
# Air Freight: GLEC
💡 **High-Level Description:**
The Global Logistics Emissions Council (GLEC) represents an unparalleled effort to standardize emissions calculations across the logistics sector. Recognizing the fragmented methodologies present in the freight domain, GLEC designed a comprehensive framework tailored specifically for air freight. This framework emphasizes consistent emissions reporting and consolidation, understanding that standardized data leads to informed decision-making.
GLEC's methodology for air freight factors in the diverse fleet compositions, varying load efficiencies, and distinct routes that shape the aviation logistics landscape. By accounting for these nuances, it provides businesses with a tool to monitor, report, and ultimately reduce their carbon footprints, while maintaining operational efficiency. With the GLEC framework in place, air freight companies can confidently navigate the intersection of economic growth and sustainable operations.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "air_freight",
"external_reference": "test_1",
"origin": "LHR",
"destination": "HAM",
"weight_in_tonnes": 2,
"plane_type": "belly_freighter",
"energy_scope": "ttw",
"methodology": "GLEC"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "air_freight",
"external_reference": "test_1",
"origin": "LHR",
"destination": "HAM",
"weight_in_tonnes": 2,
"plane_type": "belly_freighter",
"energy_scope": "ttw",
"methodology": "GLEC"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"air_freight"` (required)
* `"methodology"`: `"GLEC"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"plane_type"`: Values are `belly_freighter`, `freighter` and `average`. Default is `average`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"plane_type": "belly_freighter"`
* `"energy_scope": "wtw"`
### **Sample API Response**
```json
{
"carbon_quantity": 1654776,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 1654776,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "air_freight",
"methodology": "GLEC",
"distance": 846.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 1654776,
"co2e_emissions_wtw_in_g": 2093004,
"co2e_per_tonne_km_in_g": 978,
"tonne_km": 1692,
"reporting_year": 2024,
"transportation_mode": "air_transportation"
}
}
}
]
}
```
Smart Freight Center helped us fine tune our calculations of all freight and logistics related operations in accordance with the GLEC framework.
### **Bibliography**
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
* Towards efficient and zero emissions (n.d.). Smart Freight Centre. Retrieved from
# Inland Waterways
Inland waterways, our rivers and canals, serve as vital lifelines for many economies, providing eco-friendlier transportation alternatives. Yet, they too contribute to the carbon footprint as vessels traverse these waterways, burning fuels that emit CO2 and other greenhouse gases.
SQUAKE offers a beacon of sustainability for this sector. By providing meticulous carbon emission calculations for each voyage, companies operating on inland waterways can now seamlessly integrate SQUAKE's solutions. It's a stride towards blending traditional transportation with modern-day eco-consciousness, ensuring that our rivers remain a symbol of both trade and sustainability.
# Inland Waterways: GLEC
💡 **High-Level Description:**
The Global Logistics Emissions Council (GLEC) has established itself as a pivotal entity in shaping the approach towards calculating and reducing carbon footprints within logistics operations, including the Inland Waterways sector. GLEC's framework, recognized globally, is comprehensive and adaptable, catering to the varied aspects of logistics, from road freight to aviation and, indeed, to inland waterways.
For Inland Waterways, the GLEC methodology places a keen focus on vessel operational specifics, such as engine types, fuel consumption, and loading efficiencies. Moreover, GLEC's approach incorporates emissions not only from the actual vessel operation but also from the broader logistics chain, including cargo handling and transportation to and from port facilities. This holistic perspective ensures that all carbon sources linked to inland waterway transport are captured, laying a foundation for informed decision-making and emission reduction strategies.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "inland_waterways",
"external_reference": "test_1",
"origin": "DEBER",
"destination": "DEFRA",
"weight_in_tonnes": 20,
"vessel_type": "pushed_convoy_push_boat_2_barges",
"energy_scope": "ttw",
"methodology": "GLEC"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "inland_waterways",
"external_reference": "test_1",
"origin": "DEBER",
"destination": "DEFRA",
"weight_in_tonnes": 20,
"vessel_type": "pushed_convoy_push_boat_2_barges",
"energy_scope": "ttw",
"methodology": "GLEC"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"inland_waterways"` (required)
* `"methodology"`: `"GLEC"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"vessel_type"`: Values are `container_vessel_110_m`, `container_vessel_135_m`, `container_vessel_coupled_convoys`, `coupled_convoys`, `motor_vessels_under_50_m`, `motor_vessels_under_80_m`, `motor_vessel_under_110_m`, `motor_vessel_135_m`, `pushed_convoy_push_boat_2_barges`, `pushed_convoy_push_boat_4_5_barges`, `pushed_convoy_push_boat_6_barges`, or `tanker_vessel`. Default value is `motor_vessels_under_50_m`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"vessel_type": "motor_vessels_under_1000_t"`
* `"energy_scope": "wtw"`
### **Sample API Response**
```json
{
"carbon_quantity": 143256,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 143256,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "inland_waterways",
"methodology": "GLEC",
"distance": 508.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 143256,
"co2e_emissions_wtw_in_g": 185928,
"co2e_per_tonne_km_in_g": 14,
"tonne_km": 10160,
"reporting_year": 2024,
"transportation_mode": "inland_waterways_transportation"
}
}
}
]
}
```
Smart Freight Center helped us fine tune our calculations of all freight and logistics related operations in accordance with the GLEC framework.
## **Bibliography**
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
* Towards efficient and zero emissions (n.d.). Smart Freight Centre. Retrieved from
# Logistics Site
Logistic sites, from sprawling warehouses to distribution centers, form the backbone of the global supply chain. However, their operational complexities—equipment usage, energy consumption, and vehicular movements—generate substantial carbon emissions, often overlooked in the larger supply chain picture.
SQUAKE's precise solution for logistic sites empowers operators to meticulously quantify these emissions. This insight paves the way for sustainable strategies, from energy-efficient equipment choices to streamlined operations, ensuring that the vital cogs of the supply chain function with an eco-conscious mindset.
# Logistics Site: GLEC
💡 **High-Level Description:**
The Global Logistics Emissions Council (GLEC) serves as a pioneering organization when it comes to framing standardized approaches for calculating greenhouse gas emissions in logistics. Their emphasis is particularly evident in the area of logistics sites—those central hubs where goods are stored, managed, and dispatched. Given the high energy consumption and associated emissions of these sites, accurate calculation becomes paramount. GLEC's methodology presents an integrated approach to logistics emissions accounting. It captures a holistic view, encompassing all activities within a logistics site—from storage cooling systems to material handling equipment.
By offering a consistent, globally recognized standard, GLEC enables logistics sites worldwide to measure, manage, and reduce their carbon footprint. Their framework ensures a level playing field, fostering a more sustainable and competitive global logistics industry. The integration of direct and indirect emissions sources within the framework also ensures a comprehensive understanding of a logistics site's total environmental impact, enabling effective mitigation strategies.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "logistics_hub",
"external_reference": "test_1",
"weight_in_tonnes": 8,
"methodology": "GLEC",
"logistics_site_type": "storage_and_transhipment",
"condition_type": "ambient"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "logistics_hub",
"external_reference": "test_1",
"weight_in_tonnes": 8,
"methodology": "GLEC",
"logistics_site_type": "storage_and_transhipment",
"condition_type": "ambient"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"logistics_hub"` (required). As of GLEC v3.2, `logistics_hub` is the preferred value; `logistics_site` remains accepted for backward compatibility.
* `"methodology"`: `"GLEC"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"weight_in_tonnes"`: Numeric value.
* `"logistics_site_type"`: Values are `transhipment_site`, `storage_and_transhipment`, `warehouse`, `maritime_container_terminal`, or `liquid_bulk_terminal`. Default value is `warehouse`.
* `"condition_type"`: `temperature_controlled` is only relevant for logistics site type `maritime_container_terminal`. Values are `ambient`, `mixed`, or `temperature_controlled`. Default value is `mixed`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"logistics_site_type": "storage_and_transhipment"`
* `"condition_type": "mixed"`
### **Sample API Response**
```json
{
"carbon_quantity": 16800,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 16800,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "logistics_hub",
"methodology": "GLEC",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 16800,
"co2e_per_tonne_in_g": 2100,
"reporting_year": 2024,
"transportation_mode": "logistics_site"
}
}
}
]
}
```
Smart Freight Center helped us fine tune our calculations of all freight and logistics related operations in accordance with the GLEC framework.
## **Bibliography**
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
* Towards efficient and zero emissions (n.d.). Smart Freight Centre. Retrieved from
# Rail Freight
Rail freight, lauded for its efficiency in transporting goods over vast distances, has a distinct carbon profile. While it's often more carbon-efficient than road transport, the emissions generated from rail freight, particularly from non-electrified lines, still contribute to global greenhouse gas accumulations.
Integrating SQUAKE's solution into rail freight operations provides a precise assessment of these emissions, empowering companies to make informed decisions. With SQUAKE, rail transporters can enhance their green credentials, aligning sustainability with efficiency in this pivotal sector of logistics.
# Rail Freight: DIN EN 16258
💡 **High-Level Description:**
DIN EN 16258 is a standard that addresses the methodology for the calculation and declaration of energy consumption and greenhouse gas (GHG) emissions related to transportation services. Within the sphere of rail freight, this standard plays a pivotal role in ensuring standardized, transparent, and accurate reporting of GHG emissions. Rail freight, as an essential segment of the transport industry, has distinctive energy consumption patterns and emission profiles.
DIN EN 16258 offers a comprehensive framework for the sector by considering various facets of rail freight operations. From the type of fuel used to the weight and type of goods transported, distance covered, and even the type of rail infrastructure in place, every variable has an impact on the overall carbon footprint. The methodology is particularly valued because it allows for consistency in reporting across the European Union, ensuring comparability and benchmarking among various rail operators. By following the stipulations and recommendations of DIN EN 16258, rail freight operators can derive clear, actionable insights on their environmental footprint and identify potential avenues for improvement.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "rail_freight",
"external_reference": "test_1",
"origin": "HAM",
"destination": "BER",
"weight_in_tonnes": 41,
"methodology": "DIN-EN-16258",
"energy_scope": "wtw"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "rail_freight",
"external_reference": "test_1",
"origin": "HAM",
"destination": "BER",
"weight_in_tonnes": 41,
"methodology": "DIN-EN-16258",
"energy_scope": "wtw"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"rail_freight"` (required)
* `"methodology"`: `"DIN-EN-16258"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"train_type"`: Values are `500t`, `1000t`, `1500t`, `2000t` Default value is `1000t`.
* `"fuel_type"`: Values are `electricity` and `diesel`. Default value is `diesel`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"train_type": "1000t"`
* `"fuel_type": "diesel"`
* `"energy_scope": "wtw"`
### **Sample API Response**
```json
{
"carbon_quantity": 256789,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 256789,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "rail_freight",
"methodology": "DIN-EN-16258",
"distance": 292.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "DIN-EN-16258",
"data": {
"fuel_consumption_per_tonne_km": 1.5,
"fuel_to_co2": 3.14,
"train_type": "1000t",
"reporting_year": 2024,
"transportation_mode": "rail_transportation"
}
}
}
]
}
```
### **Bibliography**
* Method for Calculating and Declaring Energy Consumption (2013, March). DIN EN 16258.
# Rail Freight: ECTA
💡 **High-Level Description:**
The European Chemical Transportation Association (ECTA) plays a pivotal role in the European logistics and transportation realm, particularly in devising and promoting environmentally sustainable practices. In the rail freight sector, ECTA's methodologies for assessing carbon emissions emphasize precision and a holistic approach. Given that rail is already one of the more eco-efficient methods of transporting goods, particularly in the context of chemical transportation, ECTA's guidelines help further harness this potential.
ECTA's methodology focuses on the finer nuances of rail operations, from the specific type of fuel utilized to the kind of cargo, train length, and route efficiency. By integrating real-world operational data with rigorous carbon calculation methods, the ECTA provides rail freight operators with a tangible roadmap to understand and subsequently reduce their greenhouse gas emissions. The framework not only ensures compliance with European environmental standards but also inspires confidence among stakeholders and clients about the industry's commitment to sustainability.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "rail_freight",
"external_reference": "test_1",
"distance_in_km": 100,
"weight_in_tonnes": 10,
"train_type": "container_train_intermodal",
"fuel_type": "diesel",
"methodology": "ECTA"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "rail_freight",
"external_reference": "test_1",
"distance_in_km": 100,
"weight_in_tonnes": 10,
"train_type": "container_train_intermodal",
"fuel_type": "diesel",
"methodology": "ECTA"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"rail_freight"` (required)
* `"methodology"`: `"ECTA"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"train_type"`: Values are `average`, `container_train_intermodal`, `blocktrain_rtc`, or `single_wagon_train_rtc`. Default value is `average`.
* `"fuel_type"`: Values are `electricity`, `average` and `diesel`. Default value is `average`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"train_type": "average"`
* `"fuel_type": "average"`
### **Sample API Response**
```json
{
"carbon_quantity": 28000,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 28000,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "rail_freight",
"methodology": "ECTA",
"distance": 100.0,
"distance_unit": "kilometer"
}
]
}
```
## **Bibliography**
* Guidelines for Measuring and Managing CO Emission (2011, March). ECTA. Retrieved from
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
# Rail Freight: GLEC
💡 **High-Level Description:**
The Global Logistics Emissions Council (GLEC) is at the forefront of creating a unified approach for the calculation and reporting of logistics greenhouse gas emissions. In the realm of rail freight, the GLEC Framework is pivotal, offering a harmonized method that spans across all logistics sectors. As rail freight already stands as an eco-favorable choice for cargo movement, the incorporation of GLEC's methodology further accentuates its sustainable characteristics.
GLEC's comprehensive approach entails the consideration of factors like train type, fuel consumption, distance covered, and cargo weight. It not only allows rail freight operators to account for their emissions but also aids in the identification of potential areas for emission reductions. By providing a standardized metric system and promoting transparency, GLEC aids businesses in making informed decisions, bolstering the rail freight sector's eco-friendly stature and ensuring its alignment with global emission targets.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "rail_freight",
"external_reference": "test_1",
"origin": "OSL",
"destination": "HEL",
"weight_in_tonnes": 86,
"fuel_type": "diesel",
"load_characteristic": "coal_steel",
"methodology": "GLEC"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "rail_freight",
"external_reference": "test_1",
"origin": "OSL",
"destination": "HEL",
"weight_in_tonnes": 86,
"fuel_type": "diesel",
"load_characteristic": "coal_steel",
"methodology": "GLEC"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"rail_freight"` (required)
* `"methodology"`: `"GLEC"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"fuel_type"`: Values are `electricity`, `us_diesel`, `indian_average`, `average` and `diesel`. Default value is `average`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"load_characteristic"`: Values are `average`, `container`, `cars`, `chemicals`, `coal_steel`, `building_materials`, `manufactured_products`, `cereals`, `truck_trailer_on_train`, or `trailer_only_on_train`. Default value is `average`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"fuel_type": "diesel"`
* `"load_characteristic": "average"`
### **Sample API Response**
```json
{
"carbon_quantity": 1334170,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 1334170,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "rail_freight",
"methodology": "GLEC",
"distance": 768.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 1334170,
"co2e_emissions_wtw_in_g": 1334170,
"co2e_per_tonne_km_in_g": 20,
"tonne_km": 66048,
"reporting_year": 2024,
"transportation_mode": "rail_transportation"
}
}
}
]
}
```
Smart Freight Center helped us fine tune our calculations of all freight and logistics related operations in accordance with the GLEC framework.
### **Bibliography**
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
* Towards efficient and zero emissions (n.d.). Smart Freight Centre. Retrieved from
# Road Freight
The road freight sector, pivotal in ensuring goods reach their destinations, is simultaneously a significant contributor to global carbon emissions. With countless trucks plying the highways, the carbon output from fuel consumption and the logistics involved is undeniably substantial.
SQUAKE provides a tailored solution for this industry, calculating the precise carbon footprint of each journey and cargo. By adopting SQUAKE, logistics companies can navigate towards sustainability, ensuring that every delivery made also contributes to a cleaner, greener planet.
# Road Freight: DIN EN 16258
💡 **High-Level Description:**
The DIN EN 16258 is a European standard that addresses the methodology for calculating and declaring energy consumption and greenhouse gas emissions in transport services. This standard, specifically tailored to the transport sector, offers a structured approach for stakeholders in the road freight sector. By focusing on factors such as fuel type, vehicle efficiency, and load optimization, the DIN EN 16258 provides a comprehensive blueprint for road freight operators to quantify their carbon emissions with precision.
While its applicability spans across different modes of transportation, its relevance in road freight is notable. The methodology takes into consideration both operational emissions, stemming directly from fuel combustion, and embedded emissions, such as those related to vehicle production, maintenance, and end-of-life. The granularity of DIN EN 16258 ensures that every emission source in the road freight journey is meticulously accounted for, facilitating transparent reporting and benchmarking.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "road_freight",
"external_reference": "test_1",
"origin": "BER",
"destination": "FRA",
"weight_in_tonnes": 0.5,
"truck_type": "under_7.5_t",
"energy_scope": "ttw",
"methodology": "DIN-EN-16258"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "road_freight",
"external_reference": "test_1",
"origin": "BER",
"destination": "FRA",
"weight_in_tonnes": 0.5,
"truck_type": "under_7.5_t",
"energy_scope": "ttw",
"methodology": "DIN-EN-16258"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"road_freight"` (required)
* `"methodology"`: `"DIN-EN-16258"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"truck_type"`: Values are `under_7.5_t`, `under_12_t`, `under_24_t`, or `under_40_t`. Default value is `under_3.5_t`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `“truck_type”: "under_7.5"`
* `“energy_scope”: "wtw"`
### **Sample API Response**
```json
{
"carbon_quantity": 68994,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 68994,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "road_freight",
"methodology": "DIN-EN-16258",
"distance": 552.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "DIN-EN-16258",
"data": {
"energy_factor_ttw_in_MJ": 926,
"energy_factor_wtw_in_MJ": 1103,
"ghg_emissions_ttw_in_g": 68994,
"ghg_emissions_wtw_in_g": 83825
}
}
}
]
}
```
## **Bibliography**
* Method for Calculating and Declaring Energy Consumption (2013, March). DIN EN 16258.
# Road Freight: GLEC
💡 **High-Level Description**
The Global Logistics Emissions Council (GLEC) is a notable entity when it comes to carbon footprint measurement, especially within the realm of logistics. With its ambitious goal to drive emission reduction in logistics, GLEC has produced the GLEC Framework. This is a harmonized method particularly for the road freight sector, integrating existing methods and filling gaps where necessary.
The GLEC Framework for road freight focuses on a "well-to-wheel" approach. This considers the emissions from the production of fuel and its consumption, making it comprehensive. By accounting for vehicle types, load factors, and specific routes, GLEC ensures detailed and accurate carbon assessments. The methodology is particularly beneficial for companies seeking to improve their carbon footprint and align with global sustainability standards.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "road_freight",
"external_reference": "test_1",
"origin": "BER",
"destination": "ORY",
"weight_in_tonnes": 0.75,
"fuel_type": "diesel",
"energy_scope": "wtw",
"truck_type": "rigid_truck_under_26_gvw",
"temperature_controlled_freight": true,
"methodology": "GLEC"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "road_freight",
"external_reference": "test_1",
"origin": "BER",
"destination": "ORY",
"weight_in_tonnes": 0.75,
"fuel_type": "diesel",
"energy_scope": "wtw",
"truck_type": "rigid_truck_under_26_gvw",
"temperature_controlled_freight": true,
"methodology": "GLEC"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"road_freight"` (required)
* `"methodology"`: `"GLEC"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"truck_type"`: North American truck types are `van_under_3.5_t`, `general`, `auto_carrier`, `dray`, `expedited`, `flatbed`, `heavy_bulk`, `ltl_dry_van`, `mixed`, `moving`, `package`, `refrigerated`, `specialized`, `tanker`, `tl_dry_van`. Chinese truck types are `articulated_truck_hdv_above_49_t_gvw`, `articulated_truck_hdv_under_18_t_gvw`, `articulated_truck_hdv_under_27_t_gvw`, `articulated_truck_hdv_under_35_t_gvw`, `articulated_truck_hdv_under_40_t_gvw`, `articulated_truck_hdv_under_43_t_gvw`, `articulated_truck_hdv_under_46_t_gvw`, `articulated_truck_hdv_under_49_t_gvw`, `articulated_truck_under_24_t_gvw`, `articulated_truck_under_25_t_gvw`, `articulated_truck_under_29_t_gvw`, `articulated_truck_under_31_t_gvw`, `articulated_truck_under_60_t_gvw`, `dump_truck_hdv_above_31_t_gvw`, `dump_truck_hdv_under_16_t_gvw`, `dump_truck_hdv_under_20_t_gvw`, `dump_truck_hdv_under_25_t_gvw`, `dump_truck_hdv_under_31_t_gvw`, `dump_truck_ldt_under_4.5_t_gvw`, `dump_truck_mdt_under_10.5_t_gvw`, `dump_truck_mdt_under_12.5_t_gvw`, `dump_truck_mdt_under_5.5_t_gvw`, `dump_truck_mdt_under_7_t_gvw`, `dump_truck_mdt_under_8.5_t_gvw`, `dump_truck_under_24_t_gvw`, `dump_truck_under_25_t_gvw`, `dump_truck_under_29_t_gvw`, `dump_truck_under_31_t_gvw`, `dump_truck_under_60_t_gvw`, `rigid_truck_hdv_above_31_t_gvw`, `rigid_truck_ldt_under_4.5_t_gvw`, `rigid_truck_mdt_under_10.5_t_gvw`, `rigid_truck_mdt_under_12.5_t_gvw`, `rigid_truck_mdt_under_16_t_gvw`, `rigid_truck_mdt_under_20_t_gvw`, `rigid_truck_mdt_under_25_t_gvw`, `rigid_truck_mdt_under_31_t_gvw`, `rigid_truck_mdt_under_5.5_t_gvw`, `rigid_truck_mdt_under_7_t_gvw`, `rigid_truck_mdt_under_8.5_t_gvw`, `rigid_truck_under_24_t_gvw`, `rigid_truck_under_25_t_gvw`, `rigid_truck_under_29_t_gvw`, `rigid_truck_under_31_t_gvw`, `rigid_truck_under_60_t_gvw`, `truck__hdv_above_12_t_gvw`, `truck__ldv_under_4.5_t_gvw`, and `truck__mdv_under_12_t_gvw`. For more detailed mapping of load characteristics, fuel and truck types refer to the GLEC database. Values are `artic_truck_40_gvw_lightweight_trailer`, `artic_truck_under_34_gvw`, `artic_truck_under_40_gvw_si_engine`, `artic_truck_under_40_gvw`, `artic_truck_under_44_gvw`, `artic_truck_under_60_gvw`, `artic_truck_under_72_gvw`, `auto_carrier`, `dray`, `expedited`, `flatbed`, `general`, `heavy_bulk`, `ltl_dry_van`, `mixed`, `moving`, `package`, `refrigerated`, `rigid_truck_under_12_gvw`, `rigid_truck_under_20_gvw`, `rigid_truck_under_26_gvw`, `rigid_truck_under_32_gvw`, `rigid_truck_under_7.5_gvw`, `specialized`, `tanker`, or `tl_dry_van`. Default value is `van_under_3.5_t`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"load_characteristic"`: Values are `average`, `heavy`, `light`, or `container`. Default value is `average`.
* `"fuel_type"`: Values are `average`, `diesel`, `petrol`, `lng`, `lpg`, `bio-lng`, `hydrogen`, `electricity` or `cng`. Default value is `diesel`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
* **Default values**
* `"truck_type": "rigid-truck_under_7.5"`
* `"fuel_type": "diesel"`
* `"load_characteristic": "average"`
* **Calculation specifics**
For vans (up to 3.5 t GVW) operating in Asia (excluding China and India) and Africa, apply a 13% uplift to the regional values for Europe and South America.
For heavier vehicles (> 3.5 t GVW) in Asia (excluding China and India) and Africa, apply a 22% uplift to the regional values for Europe and South America.
For temperature-controlled vans (up to 3.5 t GVW) in Europe, South America, Asia and Africa, apply a 15% uplift to the regional values.
For temperature-controlled heavier vehicles (> 3.5 t GVW) in Europe, South America, Asia and Africa, apply a 12% uplift to the regional values.
*Uplift factors are based on GLEC Framework v3.1, page 104, and reflect extrapolated or validated regional adjustments as noted by NTM and TK'Blue.*
*As of GLEC v3.2 (2025), India has its own dedicated regional factors, in the same way China already did, and is no longer covered by the Asia-uplift approach above. China's factors are unchanged in this update; the USA, EU, and South America datasets were refreshed with updated fuel-mix factors.*
### **Sample API Response**
```json
{
"carbon_quantity": 123068,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 123068,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "road_freight",
"methodology": "GLEC",
"distance": 1127.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 123068,
"co2e_emissions_wtw_in_g": 123068,
"co2e_per_tonne_km_in_g": 130,
"tonne_km": 845,
"reporting_year": 2024,
"transportation_mode": "road_transportation"
}
}
}
]
}
```
Smart Freight Center helped us fine tune our calculations of all freight and logistics related operations in accordance with the GLEC framework.
### **Bibliography**
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
* Towards efficient and zero emissions (n.d.). Smart Freight Centre. Retrieved from
# Sea Freight
The vast expanse of our oceans witnesses a ceaseless flow of sea freight, ensuring global trade and economy thrive. However, this intricate network is also responsible for a notable share of global carbon emissions, with ships burning heavy fuel oils that emit substantial greenhouse gases.
SQUAKE addresses this marine challenge head-on, offering precise carbon calculations for every nautical mile traversed and each ton of cargo shipped. Integrating SQUAKE's solutions empowers maritime companies to sail towards a sustainable horizon, marrying commerce with conscious carbon compensations and reduction.
# Road Freight: Clean Cargo
💡 **High-Level Description**
Clean Cargo, an industry-driven collaboration within the shipping sector, is recognized for its proactive stance on environmental sustainability. To address the need for standardized carbon emissions metrics, Clean Cargo introduced its robust methodology specifically tailored for the sea freight domain. Their approach provides stakeholders within the industry a clear and comprehensive framework to gauge their environmental performance and identify areas of improvement.
Clean Cargo's methodology is data-driven, leveraging both primary and secondary sources to generate reliable carbon emission estimates. Recognizing the heterogeneity within the sea freight sector, the methodology factors in different ship types, fuel consumption patterns, operational profiles, and cargo types. By doing so, it paints a holistic picture of emissions and provides stakeholders with insights essential for targeted carbon-reducing initiatives. This methodology not only ensures consistent reporting but also spurs collaborative efforts among industry members to drive sustainability.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "sea_freight",
"external_reference": "test_1",
"origin": "LON",
"destination": "NYC",
"weight_in_tonnes": 5.5,
"cargo_type": "dry",
"energy_scope": "wtw",
"trade_lane": "trans_atlantic",
"methodology": "CLEAN-CARGO"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "sea_freight",
"external_reference": "test_1",
"origin": "LON",
"destination": "NYC",
"weight_in_tonnes": 5.5,
"cargo_type": "dry",
"energy_scope": "wtw",
"trade_lane": "trans_atlantic",
"methodology": "CLEAN-CARGO"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"sea_freight"` (required)
* `"methodology"`: `"CLEAN-CARGO"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"cargo_type"`: Values are `dry` or `reefer`. Default value is `reefer`.
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"trade_lane"`: Values are `panama`, `trans_atlantic`, `trans_suez`, `trans_pacific`, or `other`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"cargo_type": "reefer"`
* `"energy_scope": "wtw"`
*Updated for GLEC v3.2 (2025): the Clean Cargo average, trade-lane, and combined datasets were refreshed for 2025, harmonized with GLEC's global sea freight dataset. Vessel type and distance-tier logic are unchanged.*
### **Sample API Response**
```json
{
"carbon_quantity": 8312600,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 8312600,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "sea_freight",
"methodology": "CLEAN-CARGO",
"distance": 934.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "clean_cargo",
"data": {
"co2e_in_g": 8312600,
"co2e_emissions_wtw_in_g": 8312600,
"co2e_per_tonne_km_in_g": 8.9,
"tonne_km": 934000,
"reporting_year": 2024,
"transportation_mode": "sea_transportation"
}
}
}
]
}
```
### **Bibliography**
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
* Towards efficient and zero emissions (n.d.). Smart Freight Centre. Retrieved from
# Road Freight: DIN EN 16258
💡 **High-Level Description**
The DIN EN 16258 standard, established by the European Committee for Standardization (CEN), provides guidelines for the methodology to calculate and declare transport-specific energy consumption and greenhouse gas emissions. This standard is highly regarded in the logistics and transport sectors, and sea freight is no exception. Its rigorous guidelines serve as a baseline for environmental transparency and uniformity, particularly in an era where there's an escalating focus on carbon footprint accountability.
In the context of sea freight, DIN EN 16258 accounts for various variables affecting emission values, including ship type, fuel consumed, distance traveled, and cargo tonnage. By considering these factors, the methodology ensures that carbon emissions from marine transport are calculated with a high degree of accuracy. Furthermore, the adoption of such a standard across the sea freight sector facilitates more consistent benchmarking, reporting, and comparison, enabling stakeholders to formulate more effective emission reduction strategies.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "sea_freight",
"external_reference": "test_1",
"origin": "BRA",
"destination": "LAX",
"weight_in_tonnes": 98,
"methodology": "DIN-EN-16258",
"energy_scope": "wtw"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "sea_freight",
"external_reference": "test_1",
"origin": "BRA",
"destination": "LAX",
"weight_in_tonnes": 98,
"methodology": "DIN-EN-16258",
"energy_scope": "wtw"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"sea_freight"` (required)
* `"methodology"`: `"DIN-EN-16258"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"vessel_type"`: DIN-EN-16258 only considers `tanker` and `container` (default).
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"vessel_type": "container"`
* `"energy_scope": "wtw"`
### **Calculation steps**
For well-to-wheels GHG emissions of the VOS:
$$
G\_w \text{(VOS)} = F\text{(VOS)} \times g\_w
$$
For tank-to-wheels GHG emissions of the VOS:
$$
G\_t \text{(VOS)} = F\text{(VOS)} \times g\_t
$$
* $*F\text{(VOS)}*$ is the total fuel consumption used for the VOS.
* $g\_w$ is the well-to-wheels GHG emissions factor for the fuel used.
* $g\_t$ is the tank-to-wheels GHG emission factor for the fuel used.
$$
S \text{(leg)} = T\text{(leg)} \div T\text{(VOS)}
$$
$S \text{(leg)}$ is the factor used to calculate the share of the VOS’s energy and emissions which is allocated to a transport service for the leg. This share is based on relative proportions of transport activity for the leg and for the associated VOS.
$$
G\_w \text{(leg)} = G\_w\text{(VOS)} \times S\text{(leg)}
$$
$T \text{(leg)}$ is the transport service's transport activity for the leg.
$$
G\_w \text{(leg)} = G\_w\text{(VOS)} \times S\text{(leg)}
$$
$T \text{(VOS)}$ is the transport activity of the VOS which is related to the leg.
$$
G\_t \text{(leg)} = G\_t\text{(VOS)} \times S\text{(leg)}
$$
### **Sample API Response**
```json
{
"carbon_quantity": 17646134,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 17646134,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "sea_freight",
"methodology": "DIN-EN-16258",
"distance": 10674.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "DIN-EN-16258",
"data": {
"energy_factor_ttw_in_MJ": 209580,
"energy_factor_wtw_in_MJ": 228210,
"ghg_emissions_ttw_in_g": 16300681,
"ghg_emissions_wtw_in_g": 17646134
}
}
}
]
}
```
### **Bibliography**
* Method for Calculating and Declaring Energy Consumption (2013, March). DIN EN 16258.
# Road Freight: EMSA 🇪🇺
💡 **High-Level Description:**
The European Maritime Safety Agency (EMSA) is an integral entity of the European Union, primarily responsible for ensuring a high, uniform, and effective level of maritime safety, pollution prevention, and ship security. While safety is at its core, EMSA's commitment to the environment is also undeniable. In the realm of carbon calculation within the sea freight sector, EMSA provides an exhaustive methodology grounded on both maritime safety norms and environmental imperatives.
EMSA's approach to determining carbon emissions for sea freight is underpinned by detailed assessments of ships' operational data. The methodology involves analyzing fuel consumption records, monitoring systems' data, and voyage specifics. It emphasizes the criticality of accurate reporting, considering the diverse fleet that operates within European waters, from bulk carriers to container ships. By assimilating this data and applying rigorous standards, EMSA contributes to a transparent and accountable system that enables the maritime industry to reduce its carbon footprint, aligning with broader European sustainability goals.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "sea_freight",
"external_reference": "test_1",
"origin": "USNYC",
"destination": "DEBER",
"weight_in_tonnes": 24,
"vessel_model": "lita",
"vessel_type": "bulk_carrier",
"verifier_name": "verifavia_sarl",
"methodology": "EU-EMSA"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "sea_freight",
"external_reference": "test_1",
"origin": "USNYC",
"destination": "DEBER",
"weight_in_tonnes": 24,
"vessel_model": "lita",
"vessel_type": "bulk_carrier",
"verifier_name": "verifavia_sarl",
"methodology": "EU-EMSA"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"sea_freight"` (required)
* `"methodology"`: `"EU-EMSA"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"vessel_model"`: Here you can find [the database](https://squake.notion.site/6fe9340b62a840a6b840111ab2e8e1bf?v=40597c33c6334de889fe34466f6f8dee\&pvs=4).
* `"verifier_name"`: Here you can find [the database](https://squake.notion.site/6fe9340b62a840a6b840111ab2e8e1bf?v=40597c33c6334de889fe34466f6f8dee\&pvs=4).
* `"verifier_accreditation_number"`: Here you can find [the database](https://squake.notion.site/6fe9340b62a840a6b840111ab2e8e1bf?v=40597c33c6334de889fe34466f6f8dee\&pvs=4).
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
* **Default values**
* `“vessel_type”: "roro_fleet_average"`
### **Sample API Response**
```json
{
"carbon_quantity": 2119391,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 2119391,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "sea_freight",
"methodology": "EU-EMSA",
"distance": 7356.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* CO2 Emission Report (n.d.). emsa. Retrieved from
# Road Freight: GLEC
💡 **High-Level Description**
The Global Logistics Emissions Council (GLEC) framework emerges as a landmark in carbon accounting, especially pertinent to the sea freight sector. GLEC's approach provides companies with a harmonized and comprehensive method to calculate and report the carbon footprints of their logistics supply chains, including sea freight. A key strength of the GLEC framework is its universality; it is compatible with other standards and methods, which facilitates streamlined reporting and comparison across various sectors and regions.
As maritime transportation is one of the major contributors to global carbon emissions, the GLEC framework places a notable emphasis on this sector. It incorporates factors like fuel consumption, ship operational practices, and even the impact of auxiliary activities at ports. By providing guidelines that are both rigorous and actionable, the GLEC framework is a vital tool for companies aiming to reduce their carbon footprint and align with global sustainability goals.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "sea_freight",
"external_reference": "test_2",
"origin": "OSL",
"destination": "HEL",
"weight_in_tonnes": 86,
"fuel_type": "vlsfo",
"vessel_type": "liquefied_gas_tanker_under_199999_dwt",
"load_characteristic": "heavy",
"energy_scope": "ttw",
"methodology": "GLEC"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "sea_freight",
"external_reference": "test_2",
"origin": "OSL",
"destination": "HEL",
"weight_in_tonnes": 86,
"fuel_type": "vlsfo",
"vessel_type": "liquefied_gas_tanker_under_199999_dwt",
"load_characteristic": "heavy",
"energy_scope": "ttw",
"methodology": "GLEC"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"sea_freight"` (required)
* `"methodology"`: `"GLEC"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for ports use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"weight_in_tonnes"`: Numeric value.
* `"vessel_type"`: GLEC defaults to `general_cargo_under_4999_dwt`. Values are `bulk_carrier_under_9999_dwt`, `bulk_carrier_under_34999_dwt`, `bulk_carrier_under_59999_dwt`, `bulk_carrier_under_99999_dwt`, `bulk_carrier_under_199999_dwt`, `bulk_carrier_above_200000_dwt`, `chemical_tanker_under_4999_dwt`, `chemical_tanker_under_9999_dwt`, `chemical_tanker_under_19999_dwt`, `chemical_tanker_under_39999_dwt`, `chemical_tanker_above_40000_dwt`, `general_cargo_under_4999_dwt`, `general_cargo_under_9999_dwt`, `general_cargo_under_19999_dwt`, `general_cargo_above_20000_dwt`, `liquefied_gas_tanker_under_49999_dwt`, `liquefied_gas_tanker_under_99999_dwt`, `liquefied_gas_tanker_under_199999_dwt`, `liquefied_gas_tanker_above_200000_dwt`, `oil_tanker_under_4999_dwt`, `oil_tanker_under_9999_dwt`, `oil_tanker_under_19999_dwt`, `oil_tanker_under_59999_dwt`, `oil_tanker_under_79999_dwt`, `oil_tanker_under_119999_dwt`, `oil_tanker_under_199999_dwt`, `oil_tanker_above_200000_dwt`, `other_liquids_tankers_under_999_dwt`, `other_liquids_tankers_above_1000_dwt`, `ferry_ropax_under_1999_dwt`, `ferry_ropax_under_4999_dwt`, `ferry_ropax_under_9999_dwt`, `ferry_ropax_under_19999_dwt`, `ferry_ropax_above_20000_dwt`, `refrigerated_bulk_under_1999_dwt`, `refrigerated_bulk_under_5999_dwt`, `refrigerated_bulk_under_9999_dwt`, or `refrigerated_bulk_above_10000_dwt`. Mapping `vessel_type` with `fuel_type` can be found [here](https://squake.notion.site/Sea-Freight-GLEC-f1ab939702824e78b1b2ec4c702d328e?pvs=4)..
* `"energy_scope"`: Values are `ttw` or `wtw`. Default value is `wtw`.
* `"fuel_type"`: Values are `hfo`, `vlsfo`, or `mdo`. Default value is `hfo`. Mapping `vessel_type` with `fuel_type` can be found [here](https://squake.notion.site/Sea-Freight-GLEC-f1ab939702824e78b1b2ec4c702d328e?pvs=4)..
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
#### **Default values**
* `"vessel_type": "roro_fleet_average"`
* `"load_characteristic": "average"`
* `"fuel_type": "hfo"`
* `"energy_factor": "wtw"`
*Updated for GLEC v3.2 (2025): one emission factor was revised (international container vessels, energy scope calculation). Vessel categories, distance tiers, and well-to-wheel multipliers are unchanged.*
### **Sample API Response**
```json
{
"carbon_quantity": 713817,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 713817,
"carbon_unit": "gram",
"external_reference": "test_2",
"type": "sea_freight",
"methodology": "GLEC",
"distance": 883.0,
"distance_unit": "kilometer",
"algorithm_specifics": {
"algorithm_type": "glec",
"data": {
"co2e_in_g": 713817,
"co2e_emissions_wtw_in_g": 835318,
"co2e_per_tonne_km_in_g": 9,
"tonne_km": 75938,
"reporting_year": 2024,
"transportation_mode": "sea_transportation"
}
}
}
]
}
```
Smart Freight Center helped us fine tune our calculations of all freight and logistics related operations in accordance with the GLEC framework.
### **Bibliography**
* Smart Freight Centre (2025). Global Logistics Emissions Council Framework V3.2.
* Towards efficient and zero emissions (n.d.). Smart Freight Centre. Retrieved from
# Van
Vans, commonly used for transportation of goods and passengers, play a dual role in our modern world: convenience and carbon emissions. These vehicles, depending on their fuel type and load, have a distinct carbon emissions per journey.
By employing SQUAKE's meticulous carbon calculation system, van operators and businesses can now pinpoint their environmental impact. This integration not only offers transparent emissions insights but also promotes more sustainable practices within the sector, driving change one van at a time.
# Van: EEA 🇪🇺
💡 **High-Level Description**
The European Environment Agency (EEA) plays a pivotal role in guiding European nations toward sustainable futures. Concerning carbon calculations for the van sector, the EEA's methodology is underpinned by a rigorous system that focuses on emissions from vehicle operations, taking into account fuel type, engine efficiency, and the age of the vehicle. Their approach is comprehensive, considering both direct emissions from combustion and indirect emissions associated with the production and distribution of fuel.
This methodology is crucial for member states, ensuring they maintain a consistent approach when reporting their emissions to meet European Union climate objectives. By providing a standardized metric system, the EEA not only offers a harmonized view of the van sector's carbon footprint but also facilitates informed decision-making for policy adjustments and green transition strategies.
## **Sample API Requests**
### A. Without audit mode (for pre-booking/quotes)
```json
{
"expand": ["items"],
"items": [
{
"audit": false,
"type": "van",
"external_reference": "test_1",
"origin": "LON",
"destination": "MIL",
"manufacturer": "citroen",
"model": "berlingo_4x4",
"fuel_type": "diesel",
"engine_size_in_cubic_cm": 1560,
"methodology": "EU-EEA"
}
]
}
```
### B. With audit mode (for finalized/post-booking calculations)
```json
{
"expand": ["items"],
"audit_for": "",
"items": [
{
"audit": true,
"type": "van",
"external_reference": "test_1",
"origin": "LON",
"destination": "MIL",
"manufacturer": "citroen",
"model": "berlingo_4x4",
"fuel_type": "diesel",
"engine_size_in_cubic_cm": 1560,
"methodology": "EU-EEA"
}
]
}
```
> **Note:** `audit_for` is optional. Provide when calculating on behalf of a specific Auditable entity; otherwise omit.
## **API Request Items**
* `"type"`: `"van"` (required)
* `"methodology"`: `"EU-EEA"` (required)
* `"external_reference"`: A unique identifier that helps you link the resulting emissions to the requested item. Especially useful if multiple items are requested since SQUAKE cannot guarantee to keep the same order. The maximum length is 128 characters.
* `"origin"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"destination"`: SQUAKE will try to resolve the origin/destination regardless of its format. Ideally, for addresses use the Post standard, for airports use IATA/ICAO code (format: `^[A-Z]{3,4}$`, e.g., `"MUC"`), for other locations used in trade and transportation use UN/LOCODE codes (format: `^[A-Z]{2}\W?[A-Z2-9]{3}$`, e.g., `"DEHAM"`). You can also pass lat/long (format: `^[-+]?\d{1,3}\.\d{1,10}\s?,\s?[-+]?\d{1,3}\.\d{1,10}$`, e.g., `"+40.712,-74.006"`).
* `"distance_in_km"`: Prioritized over `origin` and `destination`. If you don't have a `distance_in_km`, you can use `origin` and `destination` and the distance will be automatically resolved. If you pass both `distance_in_km` and `origin`/`destination`, then `distance_in_km` will be used.
* `"manufacturer"`: Database could be found [here](https://squake.notion.site/d520ba8c8e7d46d2a5e92ad953ca1705?v=d3fdc860265f449eb32b3c5e23855b0a\&pvs=4).
* `"model"`: Database could be found [here](https://squake.notion.site/d520ba8c8e7d46d2a5e92ad953ca1705?v=d3fdc860265f449eb32b3c5e23855b0a\&pvs=4).
* `"fuel_type"`: Database could be found [here](https://squake.notion.site/d520ba8c8e7d46d2a5e92ad953ca1705?v=d3fdc860265f449eb32b3c5e23855b0a\&pvs=4).
* `"engine_size_in_cubic_cm"`: Database could be found [here](https://squake.notion.site/d520ba8c8e7d46d2a5e92ad953ca1705?v=d3fdc860265f449eb32b3c5e23855b0a\&pvs=4).
* `"audit"`: boolean (optional). Set to `true` to create immutable audit records for finalized calculations. Must be enabled for your account.
### **Sample API Response**
```json
{
"carbon_quantity": 132660,
"carbon_unit": "gram",
"items": [
{
"carbon_quantity": 132660,
"carbon_unit": "gram",
"external_reference": "test_1",
"type": "van",
"methodology": "EU-EEA",
"distance": 1206.0,
"distance_unit": "kilometer"
}
]
}
```
### **Bibliography**
* Monitoring of CO2 emissions from vans (2021, June 29). European Environment Agency. Retrieved from
# Travel Data API
Push structured trip records into SQUAKE for emissions reporting and carbon accounting.
The Travel Data API lets you ingest complete trip records — flights, hotels, car rides, and train journeys — directly into SQUAKE's reporting and analytics platform.
Use it when you want SQUAKE to store, attribute, and calculate emissions for travel data you already have, rather than performing an on-demand calculation at booking time.
***
## When to use this endpoint
| Scenario | Recommended endpoint |
| ---------------------------------------------------------------- | ----------------------------------- |
| Real-time emissions estimate at booking / point-of-sale | `POST /v2/calculations` |
| Push completed or in-progress trip records for reporting | `POST /v2/travel-data` |
| Batch-import historical travel data from a TMC or expense system | `POST /v2/travel-data` |
| Read back or reconcile what SQUAKE stored | `GET /v2/travel-data/trips` |
| Remove a trip you should not have sent | `DELETE /v2/travel-data/trips/{id}` |
The key difference: [`/v2/calculations`](/api-calculations-request-response) is a **synchronous, low-latency calculation** — you pass activities and get emissions back in one call. `/v2/travel-data` is a **data ingestion endpoint** — it accepts trip records, calculates emissions per activity, stores everything in your SQUAKE account, and makes it available for dashboards, reporting, and carbon accounting.
***
## The data model
Every request wraps one or more **trips**. A trip groups activities that belong together (e.g. a single business journey) and carries metadata like cost, traveler, and cost center.
```
trips[]
├── trip_reference (your unique ID — reusing it appends activities)
├── trip_name / purpose / status
├── start_date_utc / end_date_utc
├── booking_provider / pnr
├── amount_in_cents / currency
├── cost_center {}
└── activities[]
├── type: flight | hotel | car | train
├── methodology (optional override)
├── amount_in_cents / currency (optional per-activity spend)
├── traveler {}
└── [type-specific fields]
```
Trips can retain their overall booking cost while individual activities carry their own monetary values. Activity-level values take precedence in activity-based spend reporting.
### Supported activity types
If you omit `methodology`, SQUAKE uses your account's configured default methodology for that activity type. Pass `methodology` only when you want to override that default for a specific activity.
| Type | Available methodology overrides |
| -------- | ---------------------------------------------------------------------------------------------- |
| `flight` | ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GATE4, ICAO, TIM, TU-CHALMERS, US-EPA |
| `hotel` | DEFRA, HCMI, GREENVIEW |
| `car` | ACRISS, BASIC, DEFRA, EU-EEA, US-EPA |
| `train` | ADEME, BASE-EMPREINTE, CO2-EMISSIEFACTOREN-NL, DEFRA, GREEN-TRAVEL-PLEDGE, REM, SQUAKE, US-EPA |
***
## Environments and authentication
| Environment | Base URL |
| ----------- | ---------------------------------- |
| Sandbox | `https://api.sandbox.squake.earth` |
| Production | `https://api.squake.earth` |
All requests require an API key — pass it as a Bearer token or as the username in HTTP Basic Auth (no password). Sandbox and production are fully isolated and use separate keys. Create keys in the [SQUAKE Dashboard](https://app.squake.earth/).
> 💡 Always develop and test against the **sandbox** environment first.
***
## What to expect from the response
A successful `200` response returns:
* A **total `carbon_quantity`** across all activities in the request (in kilograms by default).
* An **`items` array** with per-activity breakdowns — each entry echoes your `external_reference`, `type`, calculated `carbon_quantity`, distance, and methodology details.
* A **`trips` array** with the ID of every trip the request persisted and the IDs of the activities written under it — your handle for reading the stored data back later.
If a single activity cannot be calculated (e.g. a missing required field), its result will contain a `methodology.errors` array rather than causing the entire request to fail.
***
## Reading data back
Ingestion is only half of it. The trip endpoints serve what SQUAKE stored:
| Endpoint | Returns |
| ------------------------------------------------ | ------------------------------------------------------------------------------------ |
| `GET /v2/travel-data/trips` | Paginated list of your stored trips, newest ingested first. |
| `GET /v2/travel-data/trips/{id}` | A single trip, addressed by SQUAKE's `id` or your own `trip_reference`. |
| `GET /v2/travel-data/trips/{trip_id}/activities` | The trip's activities, each with its traveler and the calculations persisted for it. |
| `DELETE /v2/travel-data/trips/{id}` | Deletes the trip, its activities, and their calculations. |
A trip read returns the trip as SQUAKE stored it — name, purpose, status, dates, booking provider, amount, cost center — plus the **IDs** of its activities rather than the activities themselves, so the response stays small however many activities the trip holds. The activities, their travelers, their additional-methodology calculations and their audit references are read through the activities endpoint.
The `trips` array of a submission is narrower on purpose: it echoes the trip's identity (`id`, `trip_reference`, `client_id`, `submitted_by_client_id`, `activity_ids`) — the handle you need to read the rest back.
***
## Next steps
→ [Create Travel Data Items](/travel-data/create-travel-data-items) — full endpoint reference with copy-paste request/response examples and field-by-field explanations.
→ [Retrieve & Delete Travel Data](/travel-data/retrieve-travel-data) — read stored trips, activities, and calculations back, and delete a trip.
# Create Travel Data Items
Ingest trip records with nested activities via POST /v2/travel-data.
Push one or more complete trip records into SQUAKE for emissions calculation, reporting, and carbon accounting.
***
## Endpoint
### `POST /v2/travel-data`
### Authentication
* **Bearer Token** or **HTTP Basic Auth** (API key as username, no password).
### Content-Type
```
Content-Type: application/json
```
### Environments
| Environment | Base URL |
| ----------- | ---------------------------------- |
| Sandbox | `https://api.sandbox.squake.earth` |
| Production | `https://api.squake.earth` |
***
## Request envelope
```json
{
"trips": [ , ... ]
}
```
You can send multiple trips per request. Each trip must include at least one activity and a `start_date_utc`.
***
## Submitting on behalf of another client
If your account is set up to manage multiple clients (contact us to enable it), you can create child clients and push their travel data through your own credentials — no separate API key per child. Add an optional root-level `client_id` to store the trips under a descendant client:
```json
{
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"trips": [ , ... ]
}
```
* `client_id` is a client `id` (UUID) as returned by the [`/v2/clients`](https://docs-v2.squake.earth/docs/openapi/clients/get-v2-clients) endpoints.
* **Omit `client_id`** to ingest for the authenticated client — existing integrations are unaffected.
* Providing `client_id` requires this to be enabled for your account (contact us). A `client_id` outside your hierarchy returns `404` with error code `client_not_found`, and **nothing is written**.
* All trips in one request are stored under the same target client, using that client's methodologies and configuration. Your authenticated credential remains the recorded actor.
CSV imports (`/v2/travel-data/imports`) do not support `client_id`. Sandbox and production hierarchies are separate: a `client_id` from one environment is never valid in the other. See [Create Child Client](https://docs-v2.squake.earth/docs/openapi/clients/post-v2-clients) for creating and listing the clients you can act for.
***
## Trip fields
| Field | Type | Required | Description |
| -------------------- | ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `activities` | array | ✅ | One or more activity objects. |
| `start_date_utc` | string (ISO 8601) | ✅ | Trip start date. Format: `YYYY-MM-DD`. |
| `end_date_utc` | string (ISO 8601) | — | Trip end date. |
| `trip_reference` | string | — | Your unique ID for this trip. **Reusing a `trip_reference` appends activities to the existing trip** rather than creating a new one. |
| `trip_name` | string | — | Human-readable label (e.g. `"Business trip to London"`). |
| `trip_purpose` | string | — | Purpose of the trip (e.g. `"Customer workshop"`). |
| `trip_status` | string | — | Status of the trip (e.g. `"completed"`). |
| `booking_provider` | string | — | TMC or booking platform name. |
| `pnr` | string | — | Passenger Name Record (common in flight bookings). |
| `amount_in_cents` | integer | — | Total trip cost in the smallest currency unit. Must be positive when `currency` is provided. |
| `currency` | string | — | ISO 4217 currency code (e.g. `"EUR"`). |
| `cost_center` | object | — | Cost center for attribution. See below. |
| `audit_for` | string | — | UUID of an Auditable entity — associates the trip with a legal entity in audit logs. |
| `metadata` | object | — | Arbitrary key-value pairs for your own use. |
| `project_reference` | string | — | Internal project or campaign reference. |
| `booking_id` | string | — | Booking system ID. |
| `external_source` | string | — | Name of the external system that created the trip. |
| `external_source_id` | string | — | ID of the trip in that external system. |
> **`trip_reference` and upsert behaviour** If you send a request with a `trip_reference` that already exists, the new activities are **appended** to that trip — no duplicate is created. Useful for incremental imports where segments are ticketed at different times. Omitting `trip_reference` creates a new trip on every call.
### Cost center fields
| Field | Type | Required | Description |
| ---------------- | ------ | -------- | --------------------------------------------------------- |
| `name` | string | ✅ | Name of the cost center. |
| `email` | string | ✅ | Contact email. |
| `purpose` | string | — | Description or purpose. |
| `department` | string | — | Department name — available as a filter in the SQUAKE UI. |
| `business_unit` | string | — | Business unit. |
| `city` | string | — | City. |
| `country_alpha2` | string | — | ISO 3166-1 alpha-2 country code (e.g. `"DE"`). |
***
## Activity fields
All activities share a common base, then add type-specific fields.
### Common fields
| Field | Type | Required | Description |
| -------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------- |
| `type` | string | ✅ | `flight`, `hotel`, `car`, or `train`. |
| `methodology` | string | — | Optional calculation methodology override for this activity type. |
| `external_reference` | string | — | Your reference ID for this leg — echoed back in the response. |
| `amount_in_cents` | integer | — | Cost of this activity in the smallest currency unit. Must be positive when `currency` is provided. |
| `currency` | string | — | ISO 4217 currency code for this activity (e.g. `"EUR"`). |
| `start_date_utc` | string | — | Activity start date (`YYYY-MM-DD`). |
| `end_date_utc` | string | — | Activity end date (`YYYY-MM-DD`). |
| `traveler` | object | — | Traveler attached to this activity. |
If you omit `methodology`, SQUAKE uses your account's configured default methodology for that activity type. Pass `methodology` only when you want to override that default for a specific activity. The fields needed for calculation still depend on the methodology that SQUAKE resolves.
Trip-level and activity-level monetary values can be sent together and do not have to match. Use trip-level values for the overall booking and activity-level values to attribute spend to individual legs. In reporting flows that use activity spend, an activity's `amount_in_cents` and `currency` take precedence over the trip-level values. Do not send `amount_base_currency`; the API neither accepts nor returns that field.
### Traveler fields
| Field | Type | Required | Description |
| --------------- | ------ | -------- | ------------------------------------- |
| `name` | string | ✅ | Full name. |
| `email` | string | ✅ | Email address. |
| `traveler_type` | string | — | `employee`, `contractor`, or `guest`. |
| `department` | string | — | Traveler's department. |
### Flight-specific fields
| Field | Description |
| --------------------- | ----------------------------------------------------- |
| `origin` | IATA airport code (e.g. `"BER"`). |
| `destination` | IATA airport code (e.g. `"LHR"`). |
| `airline` | IATA airline code (e.g. `"LH"`). |
| `flight_number` | Flight number (e.g. `"LH2472"`). |
| `booking_class` | `economy`, `premium_economy`, `business`, or `first`. |
| `departure_date` | Departure date (`YYYY-MM-DD`). |
| `number_of_travelers` | Passenger count. |
Methodology overrides: `ADEME`, `BASE-EMPREINTE`, `CO2-EMISSIEFACTOREN-NL`, `DEFRA`, `GATE4`, `ICAO`, `TIM`, `TU-CHALMERS`, `US-EPA`.
### Hotel-specific fields
| Field | Description |
| --------------------- | ---------------------------------------------------------- |
| `name` | Hotel name — supports supplier analytics in the SQUAKE UI. |
| `country` | ISO 3166-1 alpha-2 country code (e.g. `"GB"`). |
| `city` | City name. |
| `number_of_nights` | Length of stay. |
| `number_of_travelers` | Guest count. |
| `stars` | Star rating (used by some methodologies). |
Methodology overrides: `DEFRA`, `HCMI`, `GREENVIEW`.
### Car-specific fields
| Field | Description |
| ------------------ | -------------------------------------------------------------------------------------- |
| `origin` | Pickup location (free-text address, e.g. `"London Heathrow Airport, United Kingdom"`). |
| `destination` | Drop-off location. |
| `fuel_type` | e.g. `diesel`, `petrol`, `hev`, `electricity`. |
| `car_type` | e.g. `average`, `large`. |
| `usage_type` | `rental`, `taxi`, `company`, or `personal_car`. Determines GHG scope. |
| `provider_company` | Rental or ride-hailing company (e.g. `"Hertz"`, `"Uber"`). |
| `number_of_days` | Rental duration in days. |
Methodology overrides: `ACRISS`, `BASIC`, `DEFRA`, `EU-EEA`, `US-EPA`.
### Train-specific fields
| Field | Description |
| --------------------- | -------------------------------------------------------- |
| `origin` | Origin station or city. |
| `destination` | Destination station or city. |
| `number_of_travelers` | Passenger count. |
| `train_type` | e.g. `high_speed`, `mainline`, `light`, `international`. |
| `fare_class` | e.g. `first_class`, `second_class`. |
| `fuel_type` | Fuel type if applicable. |
| `operator_name` | Operator identifier (e.g. `"sncf"`, `"db"`). |
Methodology overrides: `ADEME`, `BASE-EMPREINTE`, `CO2-EMISSIEFACTOREN-NL`, `DEFRA`, `GREEN-TRAVEL-PLEDGE`, `REM`, `SQUAKE`, `US-EPA`.
***
## Request example
A complete business trip: outbound flight BER → LHR, hotel in London, taxi from Heathrow, and the return flight. The taxi activity omits `methodology`, so SQUAKE uses the account's configured car default.
```json
{
"trips": [
{
"amount_in_cents": 248500,
"currency": "EUR",
"trip_name": "Example business trip to London",
"trip_purpose": "Customer workshop",
"trip_reference": "TRIP-EXAMPLE-002",
"trip_status": "completed",
"start_date_utc": "2026-03-10",
"end_date_utc": "2026-03-12",
"booking_provider": "Example TMC",
"pnr": "ABC123",
"activities": [
{
"type": "flight",
"methodology": "TIM",
"external_reference": "ACTIVITY-FLIGHT-OUTBOUND",
"amount_in_cents": 65000,
"currency": "EUR",
"origin": "BER",
"destination": "LHR",
"departure_date": "2026-03-10",
"booking_class": "economy",
"number_of_travelers": 1,
"airline": "LH",
"flight_number": "LH2472",
"start_date_utc": "2026-03-10",
"end_date_utc": "2026-03-10",
"traveler": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"traveler_type": "employee"
}
},
{
"type": "hotel",
"methodology": "DEFRA",
"external_reference": "ACTIVITY-HOTEL-001",
"amount_in_cents": 98500,
"currency": "EUR",
"name": "Example City Hotel",
"number_of_nights": 2,
"country": "GB",
"city": "London",
"start_date_utc": "2026-03-10",
"end_date_utc": "2026-03-12",
"number_of_travelers": 1,
"traveler": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"traveler_type": "employee"
}
},
{
"type": "car",
"external_reference": "ACTIVITY-CAR-001",
"amount_in_cents": 20000,
"currency": "EUR",
"origin": "London Heathrow Airport, United Kingdom",
"destination": "Canary Wharf, London, United Kingdom",
"fuel_type": "hev",
"car_type": "average",
"usage_type": "taxi",
"provider_company": "Example Ride Provider",
"number_of_days": 1,
"start_date_utc": "2026-03-11",
"end_date_utc": "2026-03-11",
"traveler": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"traveler_type": "employee"
}
},
{
"type": "flight",
"methodology": "TIM",
"external_reference": "ACTIVITY-FLIGHT-RETURN",
"amount_in_cents": 65000,
"currency": "EUR",
"origin": "LHR",
"destination": "BER",
"departure_date": "2026-03-12",
"booking_class": "economy",
"number_of_travelers": 1,
"airline": "LH",
"flight_number": "LH2473",
"start_date_utc": "2026-03-12",
"end_date_utc": "2026-03-12",
"traveler": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"traveler_type": "employee"
}
}
],
"cost_center": {
"name": "Example Cost Center",
"purpose": "Sales",
"email": "cost-center@example.com"
}
}
]
}
```
***
## Response
### 200 OK — Example
```json
{
"carbon_quantity": 333.0,
"carbon_unit": "kilogram",
"items": [
{
"carbon_quantity": 142.6,
"carbon_unit": "kilogram",
"external_reference": "ACTIVITY-FLIGHT-OUTBOUND",
"trip_reference": "TRIP-EXAMPLE-002",
"type": "flight",
"distance": 930.0,
"distance_unit": "kilometer",
"methodology": {
"carbon": { "quantity": 142.6, "unit": "kilogram" },
"distance": { "distance": 930.0, "unit": "kilometer" },
"emission_factors": { "energy_scope": "ttw" },
"meta": { "methodology": "TIM" }
}
},
{
"carbon_quantity": 36.8,
"carbon_unit": "kilogram",
"external_reference": "ACTIVITY-HOTEL-001",
"trip_reference": "TRIP-EXAMPLE-002",
"type": "hotel",
"methodology": {
"carbon": { "quantity": 36.8, "unit": "kilogram" },
"meta": { "methodology": "DEFRA" }
}
},
{
"carbon_quantity": 14.2,
"carbon_unit": "kilogram",
"external_reference": "ACTIVITY-CAR-001",
"trip_reference": "TRIP-EXAMPLE-002",
"type": "car",
"distance": 32.0,
"distance_unit": "kilometer",
"methodology": {
"carbon": { "quantity": 14.2, "unit": "kilogram" },
"distance": { "distance": 32.0, "unit": "kilometer" },
"emission_factors": { "energy_scope": "ttw" },
"meta": { "methodology": "DEFRA" }
}
},
{
"carbon_quantity": 139.4,
"carbon_unit": "kilogram",
"external_reference": "ACTIVITY-FLIGHT-RETURN",
"trip_reference": "TRIP-EXAMPLE-002",
"type": "flight",
"distance": 930.0,
"distance_unit": "kilometer",
"methodology": {
"carbon": { "quantity": 139.4, "unit": "kilogram" },
"distance": { "distance": 930.0, "unit": "kilometer" },
"emission_factors": { "energy_scope": "ttw" },
"meta": { "methodology": "TIM" }
}
}
],
"trips": [
{
"id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"trip_reference": "TRIP-EXAMPLE-002",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"submitted_by_client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"activity_ids": [
"2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93",
"5e1a9c34-7d62-4f08-b3a1-9c4e2d7f6b58",
"c84f1d27-3e95-4b60-a7d8-2f1b9e6c4a03",
"a1d3b5c7-2e94-4f68-9b0a-7c5d3e1f8a26"
]
}
]
}
```
### Response fields
| Field | Description |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `carbon_quantity` | Total emissions across all activities, in `carbon_unit`. |
| `carbon_unit` | Unit for all carbon values — typically `kilogram`. |
| `items` | Per-activity breakdown, one entry per activity in the request. |
| `items[].external_reference` | Echoed from your request — use this to match results to input. |
| `items[].trip_reference` | Reference of the trip this item belongs to, echoed from your request. `items` are flattened across all trips, so use this to match each result back to its source trip. |
| `items[].type` | Activity type (`flight`, `hotel`, `car`, `train`). |
| `items[].carbon_quantity` | Emissions for this activity. |
| `items[].distance` | Calculated or geocoded distance (where applicable). |
| `items[].methodology` | Detailed breakdown: carbon, distance, emission factors, methodology name. |
| `items[].methodology.errors` | Present only if this activity could not be calculated. |
| `trips` | The trips this request persisted — one entry per trip, with the IDs you need to read the data back. |
| `trips[].id` | SQUAKE's identifier for the trip. |
| `trips[].trip_reference` | Echoed from your request. Usable in place of `id` when addressing the trip. |
| `trips[].client_id` | The client that **owns** the trip — the target client when you submitted with a root-level `client_id`. |
| `trips[].submitted_by_client_id` | The client whose credentials **submitted** the trip. |
| `trips[].activity_ids` | IDs of the activities **this request** wrote under the trip, in payload order. |
A `trips` entry reports the trip's **identity**, not the content you sent: it does not echo `trip_name`, `trip_status`, the dates, the amount or the cost center. Reading the trip back returns those five fields plus everything SQUAKE stored — see [Trip fields](/travel-data/retrieve-travel-data#trip-fields).
***
## Reading the data back
The `trips` array is your handle on the stored records. With those IDs — or with your own `trip_reference` — you can retrieve the trip, list its activities with the calculations persisted for each, look up the audit log behind a calculation, or delete the trip again.
Four things are only visible there, never in `items` or in the `trips` array:
* **Additional methodologies.** `items` reports the primary methodology per activity; if your account is configured with more, each additional calculation is readable through the activity's ID.
* **Audit references.** The ID of the audit log a calculation produced.
* **The trip as stored.** A trip read returns its name, purpose, status, dates, booking provider, amount and cost center — useful for checking what SQUAKE actually kept of what you sent.
* **The activity as stored.** An activity read returns its route (`origin`/`destination`), its `fuel_type` where the type has one, and the `traveler` it was booked for.
Note that `activity_ids` lists only what this request wrote. Because re-using a `trip_reference` appends activities to an existing trip, that trip may hold more than the response shows — read the trip for the full list.
→ [Retrieve & Delete Travel Data](/travel-data/retrieve-travel-data)
***
## Errors
| Status | Meaning |
| ------- | ------------------------------------------------------------------------------------------------------------------- |
| **200** | Success — check `methodology.errors` per item for partial failures. |
| **400** | Malformed request or missing required field. |
| **401** | Missing or invalid API key. |
| **404** | `client_not_found` — the `client_id` is not the authenticated client or one of its descendants. Nothing is written. |
| **500** | Internal server error. |
***
## cURL
```bash
curl --request POST "https://api.sandbox.squake.earth/v2/travel-data" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{ "trips": [ ... ] }'
```
***
## Implementation notes
**Set `external_reference` on every activity.** Response `items` are flattened across all trips in the request, so use `external_reference` to identify each activity and the echoed `trip_reference` to know which trip it belongs to. Together they let you reconcile every response item back to your input.
**Dates use ISO 8601 (`YYYY-MM-DD`).** The `_utc` suffix means SQUAKE stores and interprets them as UTC. For same-day legs, `start_date_utc` and `end_date_utc` may be identical.
**`trip_reference` is your idempotency key for trip identity.** Reuse it to incrementally add activities to a trip as segments get ticketed. Omit it to always create a new trip.
**Use activity-level monetary values for per-leg spend.** You can retain the overall booking cost on the trip and add `amount_in_cents` and `currency` to each activity. Activity values take precedence in activity-based reporting. `amount_base_currency` is not part of the public API.
**`usage_type` determines GHG scope for car activities.** Use `rental` or `taxi` for Scope 3.6 (third-party vehicles), `company` for Scope 1 (company fleet), and `personal_car` for Scope 3.6 (employee reimbursement).
**Partial failures don't fail the whole request.** An activity with an unrecognised or missing field returns `methodology.errors` — the HTTP status is still `200`. Check each item individually in error-sensitive workflows.
# Retrieve & Delete Travel Data
Read stored trips, activities, and calculations back — and delete a trip — with the /v2/travel-data/trips endpoints.
After ingestion, the trip endpoints let you read back exactly what SQUAKE stored, and delete a trip you shouldn't have sent.
Use them to reconcile your system against SQUAKE, to fetch the calculations of additional methodologies, to look up the audit log of a stored calculation, or to clean up test and duplicate data.
***
## Endpoints
| Endpoint | Returns |
| -------------------------------------------------------------- | ------------------------------------------------------------------ |
| `GET /v2/travel-data/trips` | Paginated list of your stored trips, newest ingested first. |
| `GET /v2/travel-data/trips/{id}` | A single trip. |
| `GET /v2/travel-data/trips/{trip_id}/activities` | All activities of a trip, each with its traveler and calculations. |
| `GET /v2/travel-data/trips/{trip_id}/activities/{activity_id}` | A single activity with its traveler and calculations. |
| `DELETE /v2/travel-data/trips/{id}` | Deletes the trip, its activities, and their calculations. |
### Authentication
* **Bearer Token** or **HTTP Basic Auth** (API key as username, no password) — the same credentials you use for `POST /v2/travel-data`.
### Environments
| Environment | Base URL |
| ----------- | ---------------------------------- |
| Sandbox | `https://api.sandbox.squake.earth` |
| Production | `https://api.squake.earth` |
> ℹ️ Ingesting travel data must be enabled for your account — until it is, `POST /v2/travel-data` and the CSV imports respond with `404` and error code `travel_data_not_found`. The read endpoints serve whatever is stored for you; a client with nothing stored gets an empty list.
***
## The two-level shape
A trip response carries the trip's own attributes and the **IDs** of its activities, never the activities themselves. The activities — with their traveler, calculations, and audit references — live one request away:
```
GET /v2/travel-data/trips/{id}
├── trip_reference / client_id / submitted_by_client_id
├── trip_name / trip_purpose / trip_status
├── start_date_utc / end_date_utc
├── booking_provider / amount_in_cents / currency
├── cost_center { name, purpose, email }
└── activity_ids[] ────────────┐
│
GET /v2/travel-data/trips/{id}/activities
└── activities[] ←─────────────┘
├── type / external_reference
├── origin / destination / fuel_type (by type — see below)
├── traveler { name, email, traveler_type }
└── calculations[]
├── methodology / methodology_version
├── co2_in_grams
└── audit { id }
```
This keeps a trip response small and predictable: no matter how many activities a trip holds, reading it costs one bounded response, and every endpoint that returns a trip returns the same set of fields.
The one exception is the `trips` array of a **submission**, which reports the trip's identity only — `id`, `trip_reference`, `client_id`, `submitted_by_client_id`, `activity_ids`. A read returns those five fields plus the descriptive ones above, and a shared field means the same thing in both, so a submission response and a later read of the same trip never disagree.
***
## Addressing a trip by your own reference
Everywhere a trip is addressed, you can pass **either** SQUAKE's `id` (a UUID) **or** your own `trip_reference`:
```bash
# equivalent, assuming trip_reference "TRIP-EXAMPLE-002" belongs to this trip
GET /v2/travel-data/trips/7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47
GET /v2/travel-data/trips/TRIP-EXAMPLE-002
```
That means you do not have to store SQUAKE's IDs to read your data back — if you set `trip_reference` on ingestion, your own reference is enough. Activities, by contrast, are always addressed by their SQUAKE `id`, as listed in the trip's `activity_ids`.
***
## Getting the IDs from a submission
`POST /v2/travel-data` returns a `trips` array next to the flat `items`, with the ID of every trip the request persisted and the IDs of the activities written under it:
```json
{
"carbon_quantity": 333.0,
"carbon_unit": "kilogram",
"items": [ ... ],
"trips": [
{
"id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"trip_reference": "TRIP-EXAMPLE-002",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"submitted_by_client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"activity_ids": [
"2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93",
"5e1a9c34-7d62-4f08-b3a1-9c4e2d7f6b58",
"c84f1d27-3e95-4b60-a7d8-2f1b9e6c4a03",
"a1d3b5c7-2e94-4f68-9b0a-7c5d3e1f8a26"
]
}
]
}
```
Three details worth knowing:
* **One entry per trip, not per payload entry.** Two payload entries sharing a `trip_reference` resolve to the same trip and are reported once.
* **`activity_ids` covers what *****this***** request wrote.** Re-using a `trip_reference` appends activities to an existing trip, so that trip holds more activities than the submission response lists. Read the trip to get the full list.
* **A submission echoes identity, not content.** The five fields above are all a `trips` entry carries — it does not repeat the trip name, dates, amount or cost center you just sent. Read the trip to get those back as SQUAKE stored them.
***
## Trip fields
| Field | Type | Description |
| ------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string (UUID) | SQUAKE's identifier for the trip. |
| `trip_reference` | string \| null | Your own reference, echoed from ingestion. Usable in place of `id`. |
| `client_id` | string (UUID) | The client that **owns** the trip. |
| `submitted_by_client_id` | string (UUID) \| null | The client whose credentials **submitted** the trip. `null` for trips that did not arrive through `POST /v2/travel-data` (e.g. CSV imports or TMC integrations). |
| `activity_ids` | array (UUID) | IDs of the trip's activities, in ingestion order, across all activity types. |
`client_id` and `submitted_by_client_id` differ when you submit on behalf of a descendant client: the target client owns the trip, your credential is recorded as the submitter. See [Submitting on behalf of another client](/travel-data/create-travel-data-items#submitting-on-behalf-of-another-client).
**Reads return more.** On top of the five fields above, `GET /v2/travel-data/trips` and `GET /v2/travel-data/trips/{id}` return the trip as you described it on ingestion:
| Field | Type | Description |
| ------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `trip_name` | string \| null | The trip's name, echoed from ingestion. |
| `trip_purpose` | string \| null | The trip's purpose, echoed from ingestion. |
| `trip_status` | string \| null | The status the source reported (e.g. `completed`). Free-form — SQUAKE neither constrains nor normalizes it. |
| `booking_provider` | string \| null | The provider the trip was booked through, echoed from ingestion. |
| `start_date_utc` | string (date-time) \| null | Start of the trip, in UTC. Ingestion accepts a date (`2026-03-10`); reads return a date-time (`2026-03-10T00:00:00Z`). |
| `end_date_utc` | string (date-time) \| null | End of the trip, in UTC, same format. |
| `amount_in_cents` | integer \| null | The booking's own amount, in the minor unit of `currency` (`10000` is `100.00 USD`). |
| `currency` | string \| null | 3-letter ISO 4217 code of `amount_in_cents`. |
| `cost_center` | object \| null | The cost center the trip is booked against, as `{ "name", "purpose", "email" }`. The key is always present; it is `null` for a trip booked against none. |
These fields are echoed as stored, so a field you did not send on ingestion reads back as `null`. Two values SQUAKE keeps internally are deliberately not here: the amount converted into your base currency for reporting, and the cost center's department and internal id.
***
## List trips
### `GET /v2/travel-data/trips`
Returns your stored trips as a bare array, most recently ingested first. Trips from every source are listed — API submissions, CSV imports, and TMC integrations alike.
### Pagination
| Parameter | Description |
| --------- | ---------------------------------------------- |
| `page` | Page number, starting at 1. |
| `items` | Trips per page. Defaults to 20, capped at 100. |
Pagination metadata is returned in the response headers:
| Header | Meaning |
| -------------- | --------------------------------------------------------------- |
| `Current-Page` | The page returned. |
| `Page-Items` | Trips per page. |
| `Total-Pages` | Total number of pages. |
| `Total-Count` | Total number of trips. |
| `Link` | RFC 8288 links to the `first`, `prev`, `next`, and `last` page. |
### Example
```bash
curl --request GET "https://api.sandbox.squake.earth/v2/travel-data/trips?page=1&items=20" \
--header "Authorization: Bearer $ACCESS_TOKEN"
```
```json
[
{
"id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"trip_reference": "TRIP-EXAMPLE-002",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"submitted_by_client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"trip_name": "Example business trip to London",
"trip_purpose": "Customer workshop",
"trip_status": "completed",
"booking_provider": "Example TMC",
"start_date_utc": "2026-03-10T00:00:00Z",
"end_date_utc": "2026-03-12T00:00:00Z",
"amount_in_cents": 248500,
"currency": "EUR",
"cost_center": {
"name": "Example Cost Center",
"purpose": "Sales",
"email": "cost-center@example.com"
},
"activity_ids": [
"2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93",
"5e1a9c34-7d62-4f08-b3a1-9c4e2d7f6b58",
"c84f1d27-3e95-4b60-a7d8-2f1b9e6c4a03",
"a1d3b5c7-2e94-4f68-9b0a-7c5d3e1f8a26"
]
},
{
"id": "0e5c3a91-6d78-4f21-8b4e-5a2d9c1f7b60",
"trip_reference": "TRIP-EXAMPLE-001",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"submitted_by_client_id": null,
"trip_name": null,
"trip_purpose": null,
"trip_status": null,
"booking_provider": null,
"start_date_utc": "2026-02-04T00:00:00Z",
"end_date_utc": null,
"amount_in_cents": null,
"currency": null,
"cost_center": null,
"activity_ids": ["d3c7b9a5-1f48-4e02-9a6d-8b5c3f1e7d24"]
}
]
```
The second trip shows what a sparsely described source looks like: every field it did not carry reads back as `null`, and the keys are still there.
**Multi-client accounts.** If submitting on behalf of other clients is enabled for you, the list spans the authenticated client and all of its descendants — never a parent, a sibling, or an unrelated client. Read `client_id` on each trip to see which client owns it. Without that capability, you only ever see your own trips.
***
## Retrieve a single trip
### `GET /v2/travel-data/trips/{id}`
```bash
curl --request GET "https://api.sandbox.squake.earth/v2/travel-data/trips/TRIP-EXAMPLE-002" \
--header "Authorization: Bearer $ACCESS_TOKEN"
```
```json
{
"id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"trip_reference": "TRIP-EXAMPLE-002",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"submitted_by_client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"trip_name": "Example business trip to London",
"trip_purpose": "Customer workshop",
"trip_status": "completed",
"booking_provider": "Example TMC",
"start_date_utc": "2026-03-10T00:00:00Z",
"end_date_utc": "2026-03-12T00:00:00Z",
"amount_in_cents": 248500,
"currency": "EUR",
"cost_center": {
"name": "Example Cost Center",
"purpose": "Sales",
"email": "cost-center@example.com"
},
"activity_ids": [
"2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93",
"5e1a9c34-7d62-4f08-b3a1-9c4e2d7f6b58",
"c84f1d27-3e95-4b60-a7d8-2f1b9e6c4a03",
"a1d3b5c7-2e94-4f68-9b0a-7c5d3e1f8a26"
]
}
```
A single trip read and a trip in the list return the same fields — the list is the same shape, paginated.
***
## List the activities of a trip
### `GET /v2/travel-data/trips/{trip_id}/activities`
Returns every activity of the trip, in ingestion order, each with its traveler and the calculations persisted for it. A trip is a single booking, so the list is bounded and returned in full — this endpoint isn't paginated.
```bash
curl --request GET "https://api.sandbox.squake.earth/v2/travel-data/trips/TRIP-EXAMPLE-002/activities" \
--header "Authorization: Bearer $ACCESS_TOKEN"
```
```json
[
{
"id": "2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93",
"type": "flight",
"trip_id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"external_reference": "ACTIVITY-FLIGHT-OUTBOUND",
"origin": "BER",
"destination": "LHR",
"traveler": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"traveler_type": "employee"
},
"calculations": [
{
"id": "3f2a1c8e-5d47-4b91-a0c3-1e8b7d6f4a20",
"methodology": "TIM",
"methodology_version": "3.0.0",
"co2_in_grams": 142600.0,
"audit": { "id": "0194d6b4-8711-7873-899d-c8133cd742f8" }
}
]
},
{
"id": "5e1a9c34-7d62-4f08-b3a1-9c4e2d7f6b58",
"type": "hotel",
"trip_id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"external_reference": "ACTIVITY-HOTEL-001",
"traveler": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"traveler_type": "employee"
},
"calculations": [
{
"id": "8b6d4f20-9a17-4c53-b8e1-3d7a5c2f9e14",
"methodology": "DEFRA",
"methodology_version": "2026",
"co2_in_grams": 36800.0,
"audit": null
}
]
}
]
```
The example is truncated to two of the trip's four activities. Note that the hotel stay has no `origin`/`destination` keys at all — see [Keys that depend on the activity type](#keys-that-depend-on-the-activity-type).
### Activity fields
| Field | Type | Description |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | string (UUID) | Identifier of the activity, as listed in the trip's `activity_ids`. |
| `type` | string | `flight`, `hotel`, `car`, or `train`. |
| `trip_id` | string (UUID) | The trip this activity belongs to. |
| `client_id` | string (UUID) | The client that owns the activity — always the owner of its trip. |
| `external_reference` | string \| null | Your own reference, echoed from ingestion. |
| `origin` | string \| null | Where the activity started, echoed from ingestion in the format you sent it (airport code, address, UN/LOCODE, lat/long). **`flight`, `car`, `train` only.** |
| `destination` | string \| null | Where it ended, same format as `origin`. **`flight`, `car`, `train` only.** |
| `fuel_type` | string \| null | The fuel the activity was calculated with, echoed from ingestion. Accepted values depend on the methodology. **`car` and `train` only.** |
| `traveler` | object \| null | Who travelled, as `{ "name", "email", "traveler_type" }`. Always present; `null` for an activity submitted without a traveler. |
| `calculations` | array | One entry per methodology calculated for this activity, oldest first. |
### Keys that depend on the activity type
Route and fuel are only stored for the activity types that have them, and a key a type cannot have is **omitted rather than returned as `null`**:
| Type | `origin` / `destination` | `fuel_type` |
| -------- | ------------------------ | ----------- |
| `flight` | ✅ | — |
| `car` | ✅ | ✅ |
| `train` | ✅ | ✅ |
| `hotel` | — | — |
So read `type` first, and treat a missing key as "not applicable to this type" rather than "no value". `traveler`, by contrast, is present on every activity type — a `null` there means the activity was submitted without a traveler, which is common for CSV and TMC rows.
### Traveler fields
| Field | Type | Description |
| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string \| null | Name of the traveler, echoed from ingestion. |
| `email` | string \| null | Email of the traveler, echoed from ingestion and lower-cased. SQUAKE matches travelers on this within a client, so two activities for the same person return the same traveler. |
| `traveler_type` | string \| null | `employee`, `contractor`, or `guest`. |
The traveler's department, your external employee id and SQUAKE's internal traveler id are not part of this response.
### Calculation fields
| Field | Type | Description |
| --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `id` | string (UUID) | Identifier of the calculation. |
| `methodology` | string | The methodology this calculation ran under (e.g. `TIM`, `DEFRA`). |
| `methodology_version` | string \| null | Published version of that methodology for this activity type. `null` for methodologies that are not versioned. |
| `co2_in_grams` | number | Emissions in **grams** of CO₂ equivalent. |
| `audit` | object \| null | The audit log this calculation produced, as `{ "id": "..." }`, or `null` for an activity submitted without audit mode. |
> ⚠️ **Note the unit.** `co2_in_grams` is in grams, while `POST /v2/travel-data` and the calculation endpoints report `carbon_quantity` in kilograms by default.
**Reading the full audit log.** `audit` carries only the ID — pass it to [`/v2/audits/{id}`](/audits/specific-audit-log) for the immutable record of the request, response, distances, and emission factors behind the calculation.
**Routing legs are not listed.** For a `flight` activity submitted with `routing` (e.g. `BER-FRA-JFK`), the individual legs are internal segments: the routed activity carries the itinerary total, and legs appear neither in `activity_ids` nor in this list. Addressing a leg ID directly returns `404`.
***
## Retrieve a single activity
### `GET /v2/travel-data/trips/{trip_id}/activities/{activity_id}`
Activities are always addressed through their trip, so both identifiers are required.
```bash
curl --request GET "https://api.sandbox.squake.earth/v2/travel-data/trips/TRIP-EXAMPLE-002/activities/2b4d6f81-9c3e-4a57-b0d2-6e1f8a4c7b93" \
--header "Authorization: Bearer $ACCESS_TOKEN"
```
The response is a single activity object, in the shape shown above — including its `traveler` and, where the type has them, `origin`, `destination` and `fuel_type`.
***
## Additional methodologies
If your account is configured with more than one methodology for an activity type, SQUAKE persists **one calculation per methodology**. The flat `items` array of a submission only reports the primary methodology — the others are readable here:
```json
{
"id": "c84f1d27-3e95-4b60-a7d8-2f1b9e6c4a03",
"type": "car",
"trip_id": "7c9e6f2a-4b81-4d3e-9a52-1f0c8b3d5e47",
"client_id": "4fb3ec7a-92cb-471f-b75f-c3fe7c2a34d5",
"external_reference": "ACTIVITY-CAR-001",
"origin": "London Heathrow Airport, United Kingdom",
"destination": "Canary Wharf, London, United Kingdom",
"fuel_type": "hev",
"traveler": {
"name": "Jane Doe",
"email": "jane.doe@example.com",
"traveler_type": "employee"
},
"calculations": [
{
"id": "6a2e8c40-7b19-4d35-9f68-1c4b7e2a5d93",
"methodology": "DEFRA",
"methodology_version": "2026",
"co2_in_grams": 14200.0,
"audit": null
},
{
"id": "f5b1d873-2c60-4e97-a1d4-8b3f6c9e2074",
"methodology": "US-EPA",
"methodology_version": "2026",
"co2_in_grams": 15100.0,
"audit": null
}
]
}
```
***
## Delete a trip
### `DELETE /v2/travel-data/trips/{id}`
Deletes the trip and everything hanging off it — all of its activities, routing legs included, and their calculations. Responds with `204 No Content` and an empty body. Like the reads, it accepts a `trip_reference` in place of the `id`.
```bash
curl --request DELETE "https://api.sandbox.squake.earth/v2/travel-data/trips/TRIP-EXAMPLE-002" \
--header "Authorization: Bearer $ACCESS_TOKEN"
```
Three things to keep in mind:
* **Audit logs are kept.** They are an immutable record of what was calculated, so deleting a trip does not remove the audit logs its calculations produced.
* **Reporting lags a delete.** Dashboards and reporting views refresh periodically, so a deleted trip can still appear in them until the next refresh.
* **This cannot be undone.** Re-submitting the trip to `POST /v2/travel-data` restores the data, but recalculates its emissions and creates new IDs.
***
## Errors
| Status | Meaning |
| ------- | -------------------------------------------------------- |
| **204** | Delete succeeded — empty body. |
| **401** | Missing or invalid API key. |
| **404** | `travel_data_not_found` — see below. Nothing is deleted. |
| **500** | Internal server error. |
Every miss on these endpoints collapses into the same response:
```json
{
"errors": [
{
"code": "travel_data_not_found",
"detail": "The requested travel data does not exist or is not accessible."
}
]
}
```
You get it when the trip does not exist, when it belongs to a client you cannot reach, when the identifier is neither a known trip `id` nor a known `trip_reference`, and when the activity belongs to a different trip or is a routing leg. A trip you cannot access is deliberately indistinguishable from one that does not exist.
The trip **list** is the exception: it never 404s on an empty result — a client with no reachable trips gets `200` and `[]`.
***
## Implementation notes
**Set `trip_reference` on ingestion and you never need to store SQUAKE's IDs.** Your own reference addresses the trip on every read and on delete. Activity IDs, however, only come from SQUAKE — take them from the submission response or from a trip read.
**Reconcile through the trip, not the submission response.** The `trips` array of a submission reports only the identity of what that request wrote. For the complete picture of a trip — its stored attributes, its cost center, and activities added by earlier or later submissions — read the trip.
**Branch on `type` before reading an activity's route.** `origin`, `destination` and `fuel_type` are absent, not `null`, for the types that do not have them, so a parser that assumes a fixed key set will break on the first hotel stay.
**Use the activities endpoint for anything beyond the primary methodology.** Additional methodologies and audit references are not in the flat `items` array of a submission; they are here.
**Reads are eventually visible in reporting, deletes too.** These endpoints read the stored records directly and are immediately consistent; dashboards and reporting views refresh on a schedule.
***
## Related
* [Create Travel Data Items](/travel-data/create-travel-data-items) — ingest trips and activities.
* [Retrieve a specific Audit log](/audits/specific-audit-log) — the full record behind a calculation's `audit.id`.
# Notable Changes
The notable changes page provides a comprehensive overview of recent updates, enhancements, and modifications across methodologies, products, and other elements within the API. It covers various sectors including transportation, accommodation, and emissions methodologies, highlighting the latest improvements or adjustments that enhance accuracy, coverage, and usability. Each entry provides details such as the type of change (e.g., updates to existing methodologies or new releases) and the period when these updates were implemented. This allows users to stay informed on how changes may affect their integrations and calculations, ensuring that their emissions reporting remains up-to-date and compliant.
# Webhook Updates
Notable Changes
## 🔄 Important Changes Starting July 1, 2025
We're simplifying our webhook payload structure to make integration cleaner and more straightforward.
### What's Changing?
Starting **July 1, 2025**, all new webhooks will deliver a streamlined payload structure by removing the wrapper `data` key.
#### Before (Old Format)
```json
{
"data": {
"id": "file_XXX-XXX-XXX-XXX-XXX",
"filename": "SQUAKE-CompensationCertificate-euc1XXX.pdf",
"purpose": "confirmation_document",
"size": 100,
"type": "pdf",
"download_url": "https://squake.s3.eu-central-1.amazonaws.com/...."
}
}
```
#### After (New Format)
```json
{
"id": "file_XXX-XXX-XXX-XXX-XXX",
"filename": "SQUAKE-CompensationCertificate-euc1XXX.pdf",
"purpose": "confirmation_document",
"size": 100,
"type": "pdf",
"download_url": "https://squake.s3.eu-central-1.amazonaws.com/...."
}
```
### 🔐 Security Enhancement
Along with the structural change, we're updating our security implementation:
* **Previously**: Signature hash was calculated based only on the content inside the `data` key
* **Now**: Signature hash is calculated based on the entire webhook body
This provides more comprehensive payload integrity verification.
### 📅 Timeline & Compatibility
* **Effective Date**: July 1, 2025
* **Backward Compatibility**: ✅ Existing webhooks created before July 1, 2025 will continue to work with the current format
* **Action Required**: No immediate action needed for existing integrations
### 💡 Benefits
* **Cleaner Structure**: Direct access to webhook payload without unnecessary nesting
* **Improved Security**: Enhanced signature validation covering the entire payload
* **Simplified Integration**: Easier to parse and work with webhook data
### 📋 Migration Checklist
If you're planning to create new webhooks after July 1, 2025:
* [ ] Update your webhook handler to expect the new flat structure
* [ ] Adjust your signature verification logic to validate the entire body
* [ ] Test your integration with the new format before going live
### 🤝 Need Help?
If you have any questions about these changes or need assistance with migration, please don't hesitate to reach out to our support team.
# Release Notes
You can now access all **Product Release Notes** directly in our documentation.
Release notes are organized **by year and month**, making it easy to track new features, improvements, and fixes over time.
# Release Notes: 2026
Monthly Product Release Notes for **2026** — key updates, improvements, and fixes, grouped by month.
# Release Notes — July 2026
### 🚀 New Features
🚀 \[Dashboard] Flight, train & car drilldowns Click into any flight, train, or car figure on the dashboard to see the bookings behind it — no more exporting data just to answer "what's driving this number?"
🚀 \[Dashboard] Global filters Date range and scope filters now apply across the whole dashboard instead of resetting per page, so your selection carries through the full reporting experience.
🚀 \[Calculations] HCMI hotel & event emissions Hotel and event footprints can now be calculated using the industry-standard HCMI methodology, with year, hotel area, and total-energy inputs for more precise, auditable results.
🚀 \[API] Multi-account foundations The core building blocks for managing multiple linked accounts are now in place.
🚀 \[Calculations] Dutch flight methodology versions Flight calculations can now use versioned Dutch (CO2-EMISSIEFACTOREN-NL) emission factors, making results more reproducible over time.
🚀 \[Reporting] Programme settings foundations Backend and UI building blocks for defining emission-reduction programmes are now in place, ahead of full programme tracking coming later.
### 📈 Improvements
📈 \[Data Accuracy] GLEC v3.2 freight factors Sea freight, rail freight, logistics hubs, and Clean Cargo calculations now use the latest GLEC v3.2 factors, and the outdated v3.1 methodology has been retired from new calculations.
📈 \[Data Accuracy] More accurate flight CO2 reporting Improvements to how flight energy and emissions data are processed make flight CO2 figures in reports more accurate and consistent.
📈 \[Data Accuracy] More flexible source tracking Travel data can now retain previously unsupported source names, making them available as filters in reporting.
📈 \[Performance] Faster dashboards Flight, car, train, and hotel reporting dashboards now load noticeably faster, especially on first visit or with large reports.
📈 \[Performance] Faster, fresher reporting Travel spend queries run faster and report caches refresh more reliably; reporting views also now refresh automatically as new travel data comes in.
📈 \[Imports/Exports] Faster, more reliable CSV exports Travel-data and calculation-group CSV downloads now stream instead of loading the entire file into memory first, so large exports are faster and less likely to time out.
📈 \[Reporting] Purchases grouped by company Purchases made on behalf of the same company are now grouped together using normalized company names, cutting down on duplicate-looking entries in reports.
📈 \[Dashboard] Carbon Targets area removed The Carbon Targets section and its navigation entry have been removed from the dashboard.
📈 \[Integrations] Smoother booking-tool imports The pipeline that imports booking data from connected travel platforms was reworked for more reliable syncing.
📈 \[Dashboard] Ride-hailing chart simplified The ride-hailing provider breakdown chart no longer shows duration, for a cleaner view.
📈 \[API] "Logistics Site" renamed to "Logistics Hub" The GLEC "Logistics Site" activity is now called "Logistics Hub." Existing API requests keep working unchanged.
📈 \[Integrations] Traveller email now optional Traveller email addresses are now optional across supported travel-data imports.
📈 \[Stability] Security maintenance Additional backend and frontend dependencies were updated to address security advisories. No client action required.
### 🐞 Bugfixes
🐞 \[Data Accuracy] Corrected routed-flight reporting Multi-leg flights are now reported by individual segment rather than as a single combined journey, giving more accurate per-segment emissions and fixing related CSV column and label issues.
🐞 \[Data Accuracy] Fixed Clean Cargo region data Fixed malformed region data affecting some Clean Cargo ocean-freight emission figures.
🐞 \[Dashboard] Minor Overview & Reporting fixes Fixed a batch of smaller display and stability issues on the Overview and Reporting pages.
# Release Notes — June 2026
### 🚀 New Features
🚀 \[Calculations] French hotel methodology (NOS-GESTES-CLIMAT) A new ADEME-based hotel emission methodology is available across the API, dashboard, settings, and report builder. It uses a simple fixed factor per hotel night for clients aligning with French national standards.
🚀 \[Data Accuracy] DEFRA 2026 emission factors The UK Government's updated 2026 greenhouse gas conversion factors are now live for flights, trains, buses/coaches, and cars. Clients using DEFRA methodology receive the latest official figures automatically — no action required.
### 📈 Improvements
📈 \[Data Accuracy] Smarter train type mapping Switching between train emission methodologies in settings now automatically maps the correct train type, removing a source of validation errors and manual cleanup.
📈 \[API] Broader flight API support The flight calculation API now handles unresolved or masked airline codes gracefully, returning a valid result instead of an error.
📈 \[Stability] Security patches applied Applied routine security updates to keep the platform secure. No client action required.
### 🐞 Bugfixes
🐞 \[Dashboard] Overview page filters restored Fixed an issue where filters on the reporting overview page had stopped working correctly.
# Product Release Notes May 2026 – Hotels Dashboard & Train Accuracy
### 🚀 New Features
🚀 \[Dashboard] Redesigned Hotels Dashboard The Hotels Dashboard has been significantly redesigned with richer analytics for travel managers, including new hotspot charts, radar charts, tabbed views, and a distribution breakdown card. The result is a much deeper view of hotel programme performance.
### 📈 Improvements
📈 \[Data Accuracy] More accurate train emission calculations (REM) Train emissions calculated with the Rail Emission Model (REM) methodology are now more accurate. This release improves operator-specific factor resolution, fuel type handling, cross-border routing accuracy, and country-level emission factor matching.
📈 \[Performance] Faster hotel chain data lookups Hotel chain data is now cached more efficiently, improving the speed and consistency of hotel-related lookups.
### 🐞 Bugfixes
🐞 \[Dashboard] Flight routing filters working correctly again Fixed an issue where flight routing filters were not applying correctly on the flight reporting page. Filtering flights by route now returns the expected results.
# Release Notes — April 2026
### 🚀 New Features
🚀 \[Calculations] Methodology version selector now persisted Clients can now select and save their preferred methodology version directly from the dashboard. The preference is stored in their account configuration and applied automatically on future sessions.
### 📈 Improvements
📈 \[Dashboard] Flight booking class order standardised Booking class filters on the flight reporting page now always display in the standard order: Economy → Premium Economy → Business → First.
### 🐞 Bugfixes
🐞 \[Dashboard] Rental car provider filter corrected The car provider filter now correctly shows only true rental car companies. Ride-hailing services were incorrectly appearing in the provider list. Relevant for clients who analyse car travel by provider.
🐞 \[Dashboard] Trust page image upload restored Images uploaded to a client's trust page now display correctly. Trust page links and CO₂ certificates can be shared with clients without encountering a broken image.
# Release Notes — March 2026
### 🚀 New Features
🚀 \[Reporting] Save preferred emission methodology per activity type Clients can now configure a default emission calculation methodology for each travel type (flights, hotels, cars, etc.) in Reporting Setup. Settings are persisted across sessions, so reports always run with the expected methodology without manual re-selection.
🚀 \[Reporting] GreenView hotel dataset versioning Hotel emissions calculated using GreenView now support year-specific dataset versions (2021–2026). Reports can be pinned to a specific year — ideal for audits and reproducible year-over-year comparisons. The version selector is also available in the Report Builder.
🚀 \[Reporting] Filter flight reports by domestic vs. international A new filter on the flight reporting page lets clients display only domestic flights (same origin and destination country), making it easy to separate domestic from international travel at a glance.
🚀 \[Reporting] Country codes in CSV exports Flight, car, and train CSV exports now include ISO country codes for origin and destination, giving clients cleaner data for downstream reporting without extra lookups.
🚀 \[Reporting] Saved flight distance band configuration Client-specific short/medium/long-haul distance thresholds are now persisted in the backend and flow through automatically into reporting. The flight reporting page reflects each company's configured bands instead of falling back to generic defaults.
🚀 \[Imports/Exports] Automatic flight number capture during CSV import Flight numbers are now automatically extracted during CSV imports, enabling richer travel data without additional manual effort.
🚀 \[Calculations] Flexible emission recalculation Teams can now re-run emission calculations for travel data activities using a different methodology — useful for corrections and scenario comparisons.
🚀 \[Dashboard] Ride-hailing data table A new detailed info table for ride-hailing emissions is live on the dashboard, giving clients better visibility into this travel category.
### 📈 Improvements
📈 \[Reporting] Reporting cache cleared automatically after imports and methodology changes The reporting cache is now automatically invalidated after a CSV import or a methodology switch, so clients see up-to-date data immediately without needing to manually refresh.
📈 \[Reporting] Missing values shown as dash instead of zero Dashboard tables now display "–" instead of 0 for missing data, making it clearer when a value was not provided versus genuinely being zero.
📈 \[Reporting] "Avg Ticket Price" renamed to "Avg Price" The metric label has been updated across all reporting views to better reflect that it covers hotels, cars, and other travel types — not just flights.
📈 \[API] More flexible calculation payloads The API now accepts distance-only or duration-only payloads for relevant calculation types. Existing integrations are unaffected.
📈 \[Calculations] Improved car rental distance estimation Distance is now correctly derived from rental duration alone when no distance data is provided, improving accuracy for car rental records.
📈 \[Imports/Exports] Automatic whitespace trimming during import Whitespace in travel data fields is automatically trimmed during import, reducing data quality issues downstream.
📈 \[Dashboard] "Bookings" renamed to "Segments" Terminology has been updated across the platform for consistency.
📈 \[Performance] Faster reporting page load times Reporting query optimisations mean dashboards load noticeably faster for clients with large datasets.
### 🐞 Bugfixes
🐞 \[Reporting] Flight distances now consistent across dashboard and CSV export Fixed an issue where the same flight could show different distances in the dashboard versus a CSV export. Both now always derive distance from the origin/destination pair.
🐞 \[Reporting] CSV export CO₂ scope filters now applied correctly Fixed an issue where the CO₂ scope filter selection (RFI/no-RFI, TTW/WTW) was ignored in travel data CSV exports regardless of what was chosen.
🐞 \[Reporting] Car fuel type breakdown now resolves correctly from vehicle codes Fixed an issue where the fuel type breakdown on the car dashboard was not resolving fuel types from SIPP vehicle codes, causing an inflated "unknown" bucket. Reports are now more accurate and granular for clients with car rental data.
🐞 \[Reporting] Unknown airline shown consistently across all airline charts Fixed an issue where flights with missing airline information were not consistently labelled "Unknown", causing segment counts and emissions totals to appear misaligned.
🐞 \[Reporting] CO₂ values in reports now always accurate Fixed an issue where reports could display incorrect CO₂-equivalent figures under certain conditions.
🐞 \[Reporting] Airline logos now render correctly in PDF exports Fixed an issue where airline logos were sometimes missing in exported PDF reports. A clean placeholder now appears when a logo cannot be resolved.
🐞 \[Dashboard] Session stability when switching between Admin and client dashboards Fixed an issue where switching between the Admin and client dashboards could break re-login, previously requiring users to clear their browser history.
# Product Release Notes February 2026 – Smarter Reporting, Clearer Methodology
#### 🚀 New Features
* 🚀 **\[Reporting] Ride-hailing charts are here**
* Clear visibility into ride-hailing activity and emissions
* Enables easier comparisons across travel categories
* 🚀 **\[Reporting] New flight TIM charts + refreshed TIM section**
* Adds TIM cards (e.g., contrail distribution/impact, data quality tiering)
* Improves readability and structure of flight insights
* 🚀 **\[Reporting] WTW / TTW toggle on reporting pages**
* Switch between **Well-to-Wheel** and **Tank-to-Wheel** emissions in the UI
* Supports client-level rollout where applicable (feature-flag friendly)
* 🚀 **\[Reporting] Year-over-year charts now include segment breakdowns**
* Moves beyond a single aggregate line into segment-level insight
* Helps pinpoint what’s driving changes over time
* 🚀 **\[API] Methodology version now included in responses**
* Adds `methodology_version` (when applicable) for traceability
* Helps integrators validate which calculation approach was used
***
#### 📈 Improvements
* 📈 **\[Data Accuracy] Updated DEFRA emission factors + backfill support**
* Corrected emission factor values to align with the latest interpretation
* Includes a backfill script to populate corrected values post-deploy
* 📈 **\[Reporting] More readable locations + better formatting**
* City names shown instead of IATA codes where relevant
* Improved number formatting across reporting (incl. car CO₂ metrics)
* 📈 **\[Dashboard] Smoother reporting experience**
* Date filters no longer reset when switching report types
* Updated icons for Trips and Travel Spend for clearer meaning
* 📈 **\[Imports/Exports] More reliable CSV workflows**
* Travel data CSV processing refactored for correctness and stability
* CSV exports now generate properly again
* 📈 **\[API Behavior] Client-provided request data now takes priority**
* Request payload values override backend defaults where applicable
* Integrations relying on “server default wins” should re-validate behavior
***
#### 🐞 Bugfixes
* 🐞 **\[CVP] Certificate generation + values corrected**
* Fixed certificate generation in sandbox environments
* Corrected CO₂e amount shown on CVP certificates
* 🐞 **\[Reporting] Float/decimal rendering issues resolved**
* Pre-formatted floats now display correctly on reporting pages
* Prevents misleading formatting and rounding artifacts
* 🐞 **\[Dashboard] Project imagery display fixed**
* Resolved an issue where projects could show the same image incorrectly
* 🐞 **\[Stability] Smaller fixes across the platform**
* A set of minor bug fixes improving reliability and consistency
# Product Release Notes January 2026 – New Year, Smoother Reporting & Checkout (Plus Stability Wins)
#### 🚀 New Features
* 🧾 **\[Purchases] “On behalf of” filtering**
* Filter purchases by who the booking/payment was made *for* (helpful for delegated purchasing and audits).
* 📊 **\[Reporting] Yearly trending chart on the overview**
* New data services now power a **year-over-year trend view** for long-term visibility.
* 🔎 **\[Reporting] More powerful booking filters**
* Added filters for **booking class**, **geo scope**, and **distance type**.
* Enables more granular analysis and cleaner segmentation across travel programs.
***
#### 📈 Improvements
* 🧭 **\[Reporting] Date range picker UX upgrade**
* Preview updates now happen **only when you apply** changes (less jitter, fewer mis-clicks).
* ⚡️ **\[Performance] Faster reporting filters**
* Cached filter options improve responsiveness on the reporting page (especially for larger datasets).
* 🧩 **\[Reporting] New overview page building blocks**
* New UI components added to support the upcoming reporting overview experience.
* 🧾 **\[Factors] Factors page polish**
* Added a footer to SQUAKE Factors for a more complete, consistent experience.
***
#### 🐞 Bugfixes
* 🖼️ **\[Admin] Image uploads fixed**
* Resolved an issue preventing images from uploading correctly.
* 🧾 **\[Audits] CSV export & labels corrected**
* Fixed incomplete “Find Records” CSV export and corrected UI labels (e.g., Date / Unit) + empty carbon unit issues.
* 💳 **\[Checkout] Stripe purchase limit removed**
* Removed the **€250 limit**, unblocking larger checkout amounts.
* 🚆 **\[Calculations] Train computation fix**
* Corrected an issue affecting SQUAKE train calculations.
* 🧩 **\[Integrations] Index page display fixes**
* Cleaned up issues impacting the integrations index view.
* 🧾 **\[Purchases] Refund serial numbers now unique**
* Fixed refund transactions so serial numbers are properly generated and distinct.
# Release Notes: 2025
Monthly Product Release Notes for **2025** — key updates, improvements, and fixes, grouped by month.
# Product Release Notes December 2025 - Audit-Ready Upgrades, Flight GHGP, and a Smoother Reporting Experience
#### 🚀 New Features
* 🌐 **\[Checkout] German translation for the Privacy Policy**
* ✈️ **\[Calculations] Flight GHGP calculation added**
* 🧾 **\[Audits] Developers can access the audit page**
* 🖼️ **\[Dashboard] Client branding in the sidebar**
* Ability to **update the dashboard sidebar logo**
* Ability to **show client images** in the sidebar
* 🤝 **\[General] Travalyst rail factors export service**
* Automated export of SQUAKE rail factors for Travalyst usage
#### 📈 Improvements
* 🧩 **\[Integrations] ATG card now supports “On request” status** on the integrations page
* 🧾 **\[Audits] Improved CVP loading** (faster / smoother audit experience)
* 🧩 **\[Integrations] Improved styling of the Point of Sale screen**
* 🧾 **\[Audits] New endpoints for audit statistics**
* 🌍 **\[Checkout] Improved locale switching behavior** on the checkout page
* 📊 **\[Reporting] Improved date picker state handling**
* 📊 **\[Reporting] Worker added to refresh reporting caches**
* 🔄 **\[Carbon Connect] Improved entity synchronization logic**
* 📊 **\[Reporting] Better handling of “no data” states**
* ✈️ **\[Reporting] Consistent formatting for booking classes**
#### 🐞 Bug Fixes
* 🇹🇷 **\[Salesforce] Fixed client serializer Turkey edge case** + minor improvements
* 📊 **\[Reporting] AloIndex banner can only be hidden temporarily** (as intended)
* 📊 **\[Reporting] Fixed icon styles for the flights table**
* ✈️ **\[Reporting] Fixed airline name text overlap**
* 🧾 **\[General] Audits overview now hidden when audit feature flag is disabled**
* 🏠 **\[Dashboard] Fixed start page not loading data**
* 💳 **\[Dashboard] Fixed timerange filter for compensation**
* 📅 **\[Dashboard] Fixed selected date range being off by 1 day**
* ✈️ **\[Calculations] Fixed GHGP calculation**
* 🧮 **\[Calculations] Fixed DEFRA calculation**
# Product Release Notes November 2025 – AI Insights, CVP Certificates & Audit-Ready Everything
* 🤖 **\[AI Insights] First public release**
• **AI Insights** is now live – surfacing insights on top of your data (usage/details depend on your plan & configuration).
* 🧾 **\[CVP] Certificates & Auditable Entities UI**
• **CVP Certificate** released – dedicated, audit-ready certificate format.
• **Auditable Entities UI**: visual view for CVP entities linked to audits (projects, policies, contracts, etc.).
• **Audit details page** improved, now tighter with CVP and auditable entities.
* 📊 **\[Reporting] UX polish & context**
• **ALO index banner** added to **Hotel reporting** to give clearer context for interpretation.
• **Personal vs Company** pie chart is automatically hidden when one side is 100% (no more misleading “slices”).
• **Rental days** tile hidden when value is zero to reduce noise.
* ✈️ **\[TIM & Calculations] Easier inputs**
• **TIM calculations can now be run *****without***** flight number and airline** – helpful when only OD pair is available.
• **Activities now support `external_reference`** and multiple calculations per activity via that reference (better mapping between your systems and SQUAKE).
* 🧾 **\[Audits] In-product guidance**
• **Help button** added to Audits UI to guide users through audit mode & auditable entities.
***
**📈 Improvements**
* 🔍 **\[Reporting Suite] Query & UX refinements**
• Fixed and improved **reporting page queries** for more reliable results.
• Filters now behave correctly and no longer duplicate methodologies.
• Filters on reporting now **respect client scoping** (trips per client) so you don’t mix tenants.
* 🧾 **\[CVP & Audits]**
• Further improvements to **audit details pages** (layout, data clarity).
• `VAT_number` is **no longer required** for `AuditableEntity` – fewer false blocking validations.
• Audits now store extra IDs for better traceability:
– `external_policy_id` on **trips**
– `external_employee_id` on **travelers**
* 🧮 **\[Calculations & Methodologies]**
• `external_reference` now stored on **activities**, enabling multiple related calculations and better traceability.
• **base\_empreinte** methodology version updated for Flights and **US-EPA car versions** added.
• Added missing **EVA codes** for trains & buses.
• **UIC stations** updated to the latest data.
***
**🐞 Bugfixes**
* 📊 **\[Reporting]**
• Fixed reporting page queries and filters not working correctly.
• Fixed duplicated methodologies showing up in filters.
* 🧾 **\[Purchases & Checkout]**
• Fixed checkout page flow and status bubble display in the purchases table.
• Fixed failures in **certificate generation** for purchases.
* 🧮 **\[Calculations & Travel Data]**
• Fixed Travel Data API for **hotels**.
* 🧾 **\[Audits]**
• Fixed audit records that could **load endlessly**.
• Fixed methodology source URL not being saved on API audit creation.
• Audit mode fixed for multiple methodologies (including train).
* 🔌 **\[Integrations & Sync]**
• Fixed duplicate transactions errors during **Salesforce** sync.
• Improved handling of **Airplus ZIP files**.
• Fixed DB schema in Travexis read model.
* 👥 **\[Users & Roles]**
• Fixed projects cache to ensure the **correct role** is used.
• Fixed user invitation mailer failing for users without an associated client.
# Product Release Notes October 2025 – Reporting Superpowers, FLIX Bus & Audits Go Visual
* 🔌 **\[Integrations] Travexis in the UI**
• **Travexis** is now visible in the **Integrations tab**, making it easier to discover, connect, and manage the integration.
* 🧾 **\[Trips & Hotels] Richer trip context**
• **PNR** added to trip records.
• **Hotel name** surfaced on hotel entries.
→ Easier reconciliation between TMC data, invoices, and SQUAKE reporting.
* 🚌 **\[Calculations] FLIX Bus methodology**
• New **FLIX Bus–specific methodology** added, enabling more accurate emissions for FLIX Bus travel.
* 📊 **\[Reporting] New controls & exports**
• Brand-new **advanced filters** in the Reporting Suite.
• **Export options** added to Reporting, so users can pull data for BI tools or offline analysis.
• **Car usage type charts** introduced for better insight into how cars are used (e.g. rental vs. private, etc.).
* 📊 **\[Reporting] Make Reporting the default home (feature-flagged)**
• New **feature flag** to make the **Reporting page the default screen** after login (opt-in per client / environment).
* 🧾 **\[Audits] First UI for audit data**
• **Auditable Entities view** added – see which entities are tied to a given audit.
• **Audit details view** added – inspect individual audits in more detail.
• (Currently staged / rolling out gradually 📝)
* ✈️ **\[TIM Flights] Lat/Lng support & flexible inputs**
• You can now use **lat/lng** to calculate flight emissions with **Google TIM**, in addition to `distance_in_km`.
• Works regardless of whether `departure_date` is provided.
* 💰 **\[Money Collection] Cancelable purchases**
• Money Collection purchases now support a **cancel** action, aligning them with other transaction flows.
**📈 Improvements**
* ✈️ **\[Flights & Calculations]**
• Improved handling of **coordinate formats** in flight calculations.
• For **BASE-EMPREINTE**, we now fall back to the resolved **origin/destination country** when an explicit country is missing.
• Updated **fare class data** for airlines for more realistic mappings.
* 🧮 **\[Carbon Report Builder & Methodologies]**
• **Green Travel Pledge – train** methodology added to the Carbon Report Builder.
• Mapping for **Flight BASE\_EMPREINTE** updated for better consistency.
* 📊 **\[Reporting Suite] Better defaults & more accurate queries**
• Default date range now always matches the actual data window.
• Reporting URLs now always include relevant params & filters → **shareable, reproducible views**.
• Train reporting now uses **kilometers instead of miles** and corrects date usage when querying.
• Filters with no underlying data are automatically **disabled**, so you always see results.
• Queries now consistently use **trip start & end dates**, improving accuracy for multi-day trips.
• Further query & data-fetching optimizations for better performance on reporting pages.
* 🧭 **\[Travel Data]**
• Travel Data API improvements for more robust responses.
• Added **missing travel data fields**, improving analytics granularity.
* 🧩 **\[Dashboard & UX]**
• Orders page now uses **better product cards** for clearer information density.
• You can now place **orders smaller than 1 EUR** (great for testing / micro-contributions).
• Environment banner updated and made more visible & friendly.
# Product Release Notes September 2025 – Audits, Reporting Suite & Smarter Cars, Hotels, and Integrations
* 🧾 **\[Audits] Auditable entities for CVP & audit mode**
• Added **auditable entities models & controllers** so you can attach detailed context (CVP, contracts, etc.) to audits.
• Publicly documented here and ready to use with **audit mode** (API consumers + auditors will care).
* 🚗 **\[Calculations – Car / US-EPA]**
• **Car US-EPA now versioned** — allows explicit factor set selection and future-proofing.
• Added `number_of_days` support to **car calculations** to estimate distance in km when only duration is known (great for car rentals / mobility budgets).
* 🛫 **\[Calculations – Flight]**
• Removed distance correction for **Flight CO₂-Emissiefactoren** to better align with the official dataset.
* 🏨 **\[Calculations – Hotel] CRC hotel code lookup**
• Added **CRC hotel code** lookup for hotel calculations, improving hotel mapping and automation for specific partner feeds.
* 🧮 **\[Carbon Report Builder] Green Travel Pledge – Train**
• **Green Travel Pledge (train)** methodology added as an option in the Carbon Report Builder.
* 📊 **\[Reporting] New reporting suite**
• Brand-new **Reporting Suite** released, bringing more structured analytics and improved UX for Flight/Hotel/Train/Car & transaction views (client-facing ✅).
* 🔌 **\[Integrations] Travexis**
• **Travexis** added to the **Integrations tab**, making it easier to connect and manage this data source.
* 🛍️ **\[Dashboard & Orders]**
• New **product cards** on the orders page — clearer layouts and better readability.
• You can now create **orders smaller than 1 EUR** (useful for tests, pilots, or micro-contributions).
* 💶 **\[Money Collection] Metadata support**
• Money collection purchases now support **custom metadata**, and clients can set it directly — helpful for internal allocation, cost centers, or campaign tags.
**📈 Improvements**
* 🌍 **\[Calculations & Methodologies]**
• For **BASE-EMPREINTE**, we now fall back to the **resolved origin/destination country** when explicit country is missing.
• Updated **fare class data** for airlines to better match reality.
• Updated **BASE\_EMPREINTE mapping for Flight** for more consistent results.
* 🧮 **\[Train & Hotel Calculations]**
• More **train operators** added and improved error handling in **versioned train** calculations.
• Fixes and refinements for hotel types and star handling from earlier bug reports (see below).
* 📊 **\[Carbon Connect & Carbon Reports]**
• Carbon Connect now renders the **correct project unit price** for transactions.
• Carbon Reports no longer show **duplicated parameters** in the UI.
* ⚙️ **\[App & Product Pages]**
• **App start time** improved — faster initial load.
• Product Pages UI issues cleaned up for a smoother experience.
# Product Release Notes August 2025 – Green Travel Pledge, US-EPA on Rails & Analytics Glow-Up
* 🧮 **\[Calculations] Green Travel Pledge methodology**
• New **Green Travel Pledge** calculation added to the engine
• Improved handling of factors files for this methodology (more robust updates, fewer silent failures)
* 🏨 **\[Calculations – Hotels] Room type everywhere**
• **Room type** now supported across **all hotel methodologies** (SQUAKE, Greenview, HCMI, etc.)
• Fixes previous edge cases where some hotel types returned zero emissions
* 🌱 **\[Calculations – US-EPA & Trains]**
• **US-EPA train calculation** added
• **US-EPA** now selectable as a methodology in the **Carbon Report Builder**
• Support for **UIC provider codes** in train calculations
• More train operators added + better error handling in versioned train methods
* 📊 **\[Reporting & Dashboard] Analytics glow-up**
• Many new charts & graphs for **Flight, Hotel, Train, and Car** pages
• **SPP details page** added for Carbon Connect
• Transaction details page now shows **only transaction-related SPPs**, reducing noise
* 🧭 **\[Historic Google TIM] Time-travel ready**
• Ability to **update older Google TIM datasets** (historic datasets now maintainable)
* 🧑💼 **\[Admin Panel] Easier navigation for ops & CS**
• **Filtering and searching** added to **clients and projects** — faster debugging and account reviews
**📈 Improvements**
* 🧠 **\[Calculations] Accuracy & coverage**
• More operators added to **Train** calculations
• Improved error handling in **versioned train** methodologies
• Added more **LOCODEs and airports** to datasets
• Fixed stars handling in **Hotel SQUAKE** methodology
• Fixed some hotel types that previously returned **zero emissions**
• Fixed OFNK emissions discrepancy caused by **currency handling**
* 🏨 **\[Hotels & Greenview]**
• **Greenview Hotel** calculation added to the **Carbon Report Builder**
• Methodology **versioning enabled in the Carbon Report Builder** so users can explicitly pick versions (e.g. historic DEFRA / Greenview versions)
* 🌍 **\[Midoco]**
• Added support for **more types** from Midoco (client-visible for integrated Midoco setups ✅)
* 🗺️ **\[Geocoding & Maps]**
• Improved handling of **unicode** in Google Maps API requests
• If Google Maps fails, we now **fall back to OpenStreetMap** for better resilience
* 💳 **\[Carbon Connect & Certifications]**
• Fixed and improved **totals** in detailed Carbon Connect project view
• Improved handling of **line breaks** in external invoices on certifications for nicer PDFs
# Product Release Notes July 2025 - SPP Tables, DEFRA Time Travel, and a PDF Makeover
* 🔍 **\[Carbon Connect]**
• SPP tables added to project view
• Filters + navigation for SPP tables
• `external_reference` field added for SPVs
• Deleted SPVs now synced
• API endpoints for SPPs now available
* ✈️ **\[Calculations]**
• Historical DEFRA versions now enabled for Flights, Cars, Trains, Buses, and Hotels
• GreenView Hotel calculation added — improved HCMI alignment
• 2025 emission factors rolled out across all major modes
• UN LOCODE mapping added — improved location resolution
* 🌍 **\[Locations]**
• Continents now attached to location & audit logs — for smarter analytics
**📈 Improvements**
* 🧠 **\[Calculations]**
• Bolt expenditure CO₂ amount adjusted
• Default number of travelers now handled more gracefully
• Flight DEFRA now validates `energy_scope`
• Flight US-EPA now versionable
* 📄 **\[Carbon Reports]**
• `number_of_travelers` now shown as optional in Carbon Report Builder
* 📈 **\[Statistics & Metrics]**
• Improved endpoint name & environment handling
• Metrics collection/reporting improved
* 🗂️ **\[Travel Data]**
• Methodology resolution refactored for more robust matching
* 🧮 **\[Methodologies - GLEC]**
• Added TTW-specifics
• Removed deprecated van methodology
# Product Release Notes June 2025 - Money in Motion & Polished Under the Hood
* 💰 **\[API]**
• Can now create **MoneyCollectionPurchase** directly via the `/purchases` endpoint — streamlined payment flow.
* 🖼️ **\[Products]**
• New portfolio images added — fresher, more appealing visuals for client portfolios.
**📈 Improvements**
* 📊 **\[API]**
• Added type validation for calculation parameters — fewer input errors & clearer feedback.
* 🔄 **\[Products]**
• Improved handling of product cache via a background worker — faster & more reliable data.
* 🧾 **\[Calculations]**
• Default value added for number of travelers — prevents empty/missing values.
# Product Release Notes May 2025 - More Data, Smarter Payments, and Anonymized Transactions
#### 🚀 New Features
* 💰 **\[Payments]**
• New **MoneyCollection** payment method.
• New **MoneyCollectionPurchase** model — enables more flexible payment flows.
* 🌄 **\[Products]**
• Portfolio image uploads now supported — better visual customization.
* 🛫 **\[Flight]**
• Added new operator factors — more accurate flight calculations.
### 📈 Improvements
* 🚄 **\[Calculations]**
• Train operator–specific factors reintroduced + new factors added.
• TU‑CHALMERS: now supports fare class & airline inputs — more detailed outputs.
• Car EU/EEA: country field now optional + manufacturer averages used when available.
• Updated US EPA & CO₂ emissiefactoren datasets — fresher data.
• Improved handling of hotel & event cities & states — more reliable reporting.
• Added more locations & updated airline & fare class mappings — better coverage.
* 📊 **\[API]**
• Pricing tokens now included per item in calculations with pricing — more transparent pricing.
* 📊 **\[Dashboard]**
• “View more methodologies” button now enabled.
• Fixed incorrect project class display.
***
#### 🐞 Bugfixes
* 📋 **\[Midoco]**
• Fixed query in worker.
• Prevented creation of invalid configurations.
* 🧾 **\[Dashboard]**
• Fixed calls by endpoint card.
• Correct invoice state badge colors.
* 📝 **\[Audit Mode]**
• Fixed sandbox audit mode — functional again.
* 📄 **\[Credentials Page]**
• Removed confusing link to documentation — cleaner UX.
* 🗃️ Fixed storage item creation errors in SAP Concur calculation groups.
# Product Release Notes April 2025 - Dashboards, Details & Diamonds 💎
#### 🚀 New Features
* 📊 **\[Dashboard Redesign]**
• New sidebar & dashboard redesign — fresh, more intuitive layout!
• Dashboard cards updated: no more shadows & NaN values now rounded properly.
* 🏢 **\[General]**
• Company ID now shown on company info page — for easier reference.
• Product pages now display product ID + copy button — easier for clients to grab & share IDs.
* ✈️ **\[Calculations]**
• New restaurant calculation for BASE-EMPREINTE methodology — sustainable dining counts too!
• Added factors for first class travel — more accurate premium class estimates.
• Updated event HCMI factors (2024) & train CO2 EMISSIEFACTOREN (2025).
* 📄 **\[Checkout]**
• Clients can now pass an external reference when creating purchases — helps with reconciliation.
* 📄 **\[General]**
• Certificates now generated on confirm by default — less waiting.
### 📈 Improvements
* 🔗 **\[Carbon Connect]**
• Fixed Project Totals & View cards + updated transaction view — clearer & more reliable.
* 📂 **\[Portfolio View]**
• Better scroll handling on project cards + use portfolio cover for portfolio products.
* 📄 **\[Carbon Report Builder]**
• Added missing items to report builder — more complete reports.
***
#### 🐞 Bugfixes
* 🧾 **\[Calculations]**
• Fixed BASE-EMPREINTE for flights when using averages.
• Fixed Google TIM calculation.
• Fixed TU-CHALMERS when no emission factors found.
• Fixed emission factor keys for hotel cities/states.
• Adjust errors for car basic fuel intensities.
* 📄 **\[Purchases]**
• Fixed certificates not being generated properly.
* 🗃️ **\[Dashboard]**
• Fixed price caching issue & other small redesign glitches.
* 📝 **\[Carbon Report]**
• Fixed overflows in report builder.
# Product Release Notes March 2025 - Pie, Polished & Production-Ready
#### 🚀 New Features
* 🚄 **\[Calculations]**
• DEFRA train calculation support
• DEFRA bus calculation support
• ICAO code support for flight DEFRA & ICAO methodologies
• TU-CHALMERS flight calculation added — another methodology choice for clients.
* ✈️ **\[Calculations]** Base Empreinte methodology added for flights — more methodology options.
* 📈 **\[Dashboard Redesign]**
• API usage stats available via a new endpoint — helps clients monitor their usage.
• Compensation stats service added — more transparency.
* 🔗 **\[Purchases]** Certificate downloads now enabled for confirmed purchases — clearer documentation.
* 🔧 **\[Carbon Connect]**
• Project view redesigned in Carbon Connect.
• Carbon Connect officially live in production! 🎯
* 🗂️ **\[Airplus Integration]** Logic added to open ZIP-protected files — supports tricky Airplus files.
* 🖼️ **\[Settings]** New option to delete company images — cleaner admin for clients.
### 📈 Improvements
* 🏨 **\[Calculations]**
• Better type validation on hotel parameters.
• New Vincenty distance calculation method — more precise.
• Prioritize stars over `hotel_type` in HCMI.
• Handle decimal commas in CSV uploads — no more parsing errors.
* 📊 **\[Portfolio View]**
• Better handling of project data.
• Support floating-point splits for projects — better accuracy.
* 🔍 **\[Audit]**
• Google TIM dataset tier & type added to response + emission factors.
• Return algorithm specifics in audit responses — more transparency for clients.
* 🌍 **\[General]**
• Improved frontend error handling — better UX for clients.
***
#### 🐞 Bugfixes
* 🧾 **\[Purchases]**
• Fixed Stripe purchase flow through Salesforce.
• Fixed certificates not being generated properly.
* 🖼️ **\[Inventory Management]** Fixed image URL.
* 📄 **\[Dashboard]** Fixed price caching issue.
* 🧹 Various smaller bugs in hotel calculations, CSV exports, user profile styles & dashboard redesign cleaned up.
# Product Release Notes February 2025 - Audits, Portfolios & Inventories: The Power Combo
#### 🚀 New Features
* 🕵️♀️ **\[Audit]** Audit mode & related features:
• `on_behalf_of` support
• endpoints to fetch audits & audits by ID
• services to calculate & track audits
* 🏗️ **\[Inventory Management]** Inventory management preview:
• basic models added
• portfolio view added to product pages
* 📄 **\[General]** Purchase export now includes trust page, confirmation, and certificate document links — better transparency.
* 🗂️ **\[Travel Data]**
• Frontend screens for travel data upload history
• API errors now saved to a CSV file for review.
#### 📈 Improvements
* 🚄 **\[Calculations]** Base Empreinte methodology added for trains — better rail emissions reporting.
* 🌍 **\[Calculations]** Add country handling to Expenditure OFNK — more accurate for multi-country spend.
* ⚡ **\[General]** Performance improvements for GATE4 & Carbon Query — faster results for clients.
* 🏨 **\[Calculations]** Fixed hotel calculations — more accurate results.
# Product Release Notes January 2025 — First Launch of the Year: Faster, Smarter, Cleaner (Kickoff with Salesforce, TIM & DEFRA Enhancements)
* **Carbon Calculations**
• Added `energy_scope` parameter support for **DEFRA car** methodology.
• Added **DEFRA hotel** methodology to the Carbon Report Builder.
* **Travel Impact Model (TIM)**
• Historical data support added.
• Distance in km parameter now available in TIM report builder.
• Parameter logging for historical TIM Tier 3 fallback data.
* **Purchases**
• Cancellation deadline now included in purchase API responses.
**📈 Improvements**
* **General** — Removed legacy Trust Page code, updated Cloudflare router, refined caching to reload sequentially, refactored `ClientBuilder` for maintainability.
***
**🐞 Bugfixes**
* **General** — Fixed Airplus implementation, Snowflake JWT timestamp handling, and constant naming in CSV emissions import.
* **Salesforce** — Fixed project price update logic.
* **Stripe Checkout** — Payment link only returned if `payment_method: stripe` is passed.
* **Carbon Report Builder** — Fixed type badge display.
* **Travel Data** — Stats hotfix applied.
* **Webhooks** — Removed uniqueness DB constraint for improved flexibility.
* **Retirement Links** — Fixed sync logic.
* **Calculations** — Corrected hotel HCMI logic.
# Release Notes: 2024
Monthly Product Release Notes for **2024** — key updates, improvements, and fixes, grouped by month.
# Product Release Notes December 2024 - “Cytric Goes Wild: Bugs Fixed, Features Flexed, and a Whole Lot of Travel Magic!” (Expanded Integrations, GLEC v3.1 Updates & Webhook API)
* **Stripe Checkout**
• Certificates now generated for Stripe Checkout transactions.
• Added co-branding capability to the Stripe Checkout page.
* **Webhooks & API**
• Introduced **Webhooks API** for real-time event triggers.
• Feature flag to generate certificates after purchase confirmation.
• Webhooks now triggered upon certificate generation.
* **Travel Data**
• Lambda function for enhanced processing.
• Frontend handling for **manually uploaded CSV travel data**.
* **Carbon Calculations**
• Added support for **Flight DEFRA TTW energy scope**.
• Added new **SIPP fuel types** for ACRISS methodology.
***
**📈 Improvements**
* **Stripe Checkout** — Set default transaction status to "Settled"; PDF generation triggered on webhook events; cache reload after client image upload.
* **Calculations** —
• Applied distance corrections for Flight DEFRA & TIM.
• Updated **Air Freight, Rail Freight, Sea Freight, Inland Waterway, Logistics Site** methodologies to **GLEC v3.1**.
• Updated **Sea Freight Clean Cargo factors**.
• Updated **Road Freight GLEC** dataset.
* **General** —
• Used public CDN bucket for banner uploads.
• Improved webhook API error handling.
• Avoided redundant product page cache reloads.
***
**🐞 Bugfixes**
* **General** — Fixed PDF downloads, invoice URLs, portfolio display in admin dashboard, purchases table failure when payment reference is null, and Sidekiq queue issues in sandbox/production.
* **Travel Data** — Fixed worker execution in sandbox.
* **Navan Integration** — Corrected authentication URL.
# Product Release Notes November 2024 - Carbon Targets Refinements, BCD Integration & Chrome Extension
* **\[Travel Data]**
• **Lambda service** to trigger Travel Data import from uploaded files.
• File upload support for Travel Data CSVs.
• Travel Data now integrated into the CO₂ Targets dashboard.
* **\[Emissions Calculations]**
• Added **DEFRA Car calculation** to expand methodology coverage.
• Added **airline and aircraft type fields** to ADEME in Carbon Report Builder.
***
### 📈 Improvements
* **CO₂ Targets Dashboard**
• Backend + frontend integration completed.
• Added tabbed dashboard with an **"Edit Targets"** tab.
• Split dashboard into smaller, maintainable components.
* **Travel Data**
• Better handling of headers and filtering of unknown items.
• UI/UX enhancements for CSV uploads.
• Continued bug bash fixes and performance improvements.
* **Performance & Code Quality**
• Improved metrics for AWS ECS requests and CarbonQuery services.
• Cleaner admin clients endpoint payloads.
• Disabled ESLint’s shadowed variables rule for readability.
• Split policies into clearer categories for maintainability.
* **Frontend Enhancements**
• Adjusted container padding for small screens.
• Improved label rendering on charts to avoid overlaps.
• Initialized **Storybook** in design library for better component documentation.
***
### 🐞 Bugfixes
* Fixed persistent CarbonQuery connections for more stable queries.
* Corrected Travel Data endpoint to return proper S3 URLs.
* Fixed product pages cache invalidation when updating clients.
* Improved UI loading behavior.
* Hidden source link button when no retirement links are available.
* Correctly handle products passed as hashes.
* Additional Travel Data bug bash fixes for edge cases.
# Product Release Notes October 2024 - We know your targets and are you trippin? (CO₂ Targets, Travel
* **\[Travel Data]**
• **Lambda service** to trigger Travel Data import from uploaded files.
• File upload support for Travel Data CSVs.
• Travel Data now integrated into the CO₂ Targets dashboard.
* **\[Emissions Calculations]**
• Added **DEFRA Car calculation** to expand methodology coverage.
• Added **airline and aircraft type fields** to ADEME in Carbon Report Builder.
***
### 📈 Improvements
* **CO₂ Targets Dashboard**
• Backend + frontend integration completed.
• Added tabbed dashboard with an **"Edit Targets"** tab.
• Split dashboard into smaller, maintainable components.
* **Travel Data**
• Better handling of headers and filtering of unknown items.
• UI/UX enhancements for CSV uploads.
• Continued bug bash fixes and performance improvements.
* **Performance & Code Quality**
• Improved metrics for AWS ECS requests and CarbonQuery services.
• Cleaner admin clients endpoint payloads.
• Disabled ESLint’s shadowed variables rule for readability.
• Split policies into clearer categories for maintainability.
* **Frontend Enhancements**
• Adjusted container padding for small screens.
• Improved label rendering on charts to avoid overlaps.
• Initialized **Storybook** in design library for better component documentation.
***
### 🐞 Bugfixes
* Fixed persistent CarbonQuery connections for more stable queries.
* Corrected Travel Data endpoint to return proper S3 URLs.
* Fixed product pages cache invalidation when updating clients.
* Improved UI loading behavior.
* Hidden source link button when no retirement links are available.
* Correctly handle products passed as hashes.
* Additional Travel Data bug bash fixes for edge cases.
# Product Release Notes September 2024 - CO₂ Targets, Travel Data API & Enhanced Data Accuracy
* **\[CO₂ Targets]**
• Added **CO₂ Targets dashboard screen** (feature-flagged for staged rollout).
• Created backend **CO₂ targets model & controller** to support carbon tracking.
• Added baseline setting form to UI.
* **\[Travel Data & Booking Tools]**
• Added feature flag for Travel Data and Booking Tools.
• Initial draft of **Travel Data API endpoint**.
• Display metadata from Travel Data API items on dashboard.
• Added service to process CSVs into trip data for faster imports.
* **\[Certificates & Product Pages]**
• Ability to **attach company images** to clients and display on product pages.
• Added client image to products page for improved branding.
* **\[Data Import & CSV Handling]**
• Endpoint to start CSV import for easier ingestion of trip data.
***
**📈 Improvements**
* **Emissions Methodologies**
• Adjusted **accommodation** and **bus** emissions calculations for greater accuracy.
• Updated coffee values for more precise impact calculations.
• Adjusted default methodologies and added new fare class codes for expanded coverage.
* **Data & Integrations**
• Final refinements for **historic data import processing**.
• Improved project sync to include missing country data.
• Set Redis cache token on initial SAP Concur connection.
* **UI & UX**
• Optimized mobile view for product pages.
• Improved data visualization by adding new charts to frontend.
• Adjusted designs for company image upload.
• Improved label positions on charts for readability.
* **Performance & Stability**
• Bumped Ruby to **3.3.5** for performance gains.
• Updated dependencies (micromatch, webpack, OpenTelemetry for security).
• Reused AWS ECS connections for efficiency.
• Enabled locale fallbacks for missing translations.
***
**🐞 Bugfixes**
* Fixed handling of **fixed prices** and **purchase confirmations**.
* Resolved issues with **project images backfill**.
* Fixed **frontend build issues** and Stripe controller on sandbox.
* Corrected SAP Concur import route.
* Fixed squished client images on product pages.
* Corrected booking class handling in Google TIM.
* Invalidate Trust Page data when purchases are cancelled.
* Fixed cache reload read timeouts.
# Product Release Notes August 2024 - Product Pages Go Live, GATE4 Methodology & SAP Concur Trip Data
* **\[Product Pages]**
• Full public release of Product Pages in the Dashboard.
• External product list and product details pages now available.
• “Not Found” page for unavailable products.
• Pop-up for project details on the new purchase page.
* **\[Certificates & Reporting]**
• External Reference field now shown on compensation certificates.
• CSV export for calculation items.
* **\[Carbon Calculation]**
• Introduced **GATE4 methodology** in Carbon Query.
***
**📈 Improvements**
* DEFRA factor updates and ICAO seat value logic refresh.
* Added airline and fare class validations.
* Improved product details performance and UI consistency.
* Optimized caching and Redis locking for product pages.
* Better error handling for external imports.
* Additional missing airports added.
* Improved Cloudflare routing for product pages.
* Enhanced Travel Data (formerly Trip Data) charts and styles.
* Adjusted wording, filters, and pagination for product views.
***
**🐞 Bugfixes**
* Fixed DEFRA calculations when aircraft type is provided.
* Resolved format issues for numbers on orders page.
* Corrected styles on Travel Data and purchase details screens.
* Fixed handling of settled purchase state on Trust Page.
* Compensation status now correctly updates when purchase is settled.
* Fixed placeholder images in product pages with real API URLs.
* Removed visual artifacts from “product not found” images.
# Product Release Notes June-July 2024 - SAP Concur, New Integrations & Reporting Upgrades
* **\[Carbon Reporting]**
• Unlimited carbon reports quota setting for eligible clients.
• Added energy scope to CO₂ Emissiefactoren NL.
• Added support for string list input in “emissions from CSV” in Carbon Report Builder.
* **\[Trust Page]**
• Second retirement link for retired purchases.
• Adjustments for improved display and usability.
* **\[Purchase Details]**
• New purchase detail screen.
• Payment reference ID now included in purchase export.
***
**📈 Improvements**
* Updated EPA factors for more accurate calculations.
* Enhanced Carbon Report Builder functionality and resolved edge-case errors.
* Expanded admin panel with additional info.
* Standardized logging and metrics across services.
* Purchase history CSV export refinements (removing ambiguous columns).
* Aligned purchase filters and icon styles in purchases table.
* Added fallback to CAR US-EPA.
* Trip data now includes more specific per-type details.
* Performance boosts to internal purchase index endpoint.
* Infrastructure and dependency maintenance.
***
**🐞 Bugfixes**
* Fixed carbon credit “canceled” state display.
* Corrected user role assignment in sandbox.
* Fixed flight number parsing issues.
* Resolved payment status and invoice price mismatches.
* Fixed customer-facing issues with sandbox switch and confirmations.
* Added fuel\_type validations for CAR BASIC methodology.
* Corrected CO₂ transaction status sync in Salesforce.
* Mapped Salesforce `Payment_Date__c` to `paid_on` in invoices.
* Fixed staging image base URLs for projects.
* Corrected type conversion errors in Carbon Report Builder.
---
[Next Page](/llms-full.txt/1)