get https://api.searoutes.com/co2/v2/plan
This endpoint returns CO₂ equivalent (CO₂e) emissions statistics of a given carrier and port pair.
We calculate the itineraries operated by the carrier based on their services (and their alliance's) and for each itinerary, we calculate the CO₂e emissions of each vessel operating the service and return statistics. The response provides CO₂e emissions data at two levels:
- at the carrier level,
- at each itinerary level.
Response
CO₂ emissions overview
The CO₂e emissions are returned in grams.
| Field | Given at carrier level | Given at itinerary level |
|---|---|---|
co2e.min | Greenest itinerary average emissions | Greenest vessel emissions of a specific itinerary |
co2e.max | Most emitting itinerary emissions | Most emitting vessel emissions of a specific itinerary |
co2e.average | Average CO₂e emissions for all itineraries | Average CO₂e emissions of all vessels of a specific itinerary |
co2e.standardDeviation | Standard deviation of CO₂e emissions across itineraries | Standard deviation of CO₂e emissions across vessels operating a specific itinerary |
Other fields
- CO₂ breakdown (WTT, TTW, and intensity) is provided for each CO₂e emissions value in the response.
- Distance is only given at the itinerary level. The distance takes into account the ports of call based on the services proformas.
- A hash (
itineraries.hash) is assigned to each itinerary, acting as a unique identifier for that specific route and shipment characteristics.- The corresponding itinerary can be retrieved via the
GET /itinerary/v2/proformas/{hash}endpoint. - This endpoint provides additional itinerary details, including ports of call and route geometry.
- The corresponding itinerary can be retrieved via the
Notes & Considerations
- For the calculation of the emissions:
- if no container info is provided but the weight is, we assume the container number based on the weight.
- if none of the above is provided, we assume 1 TEU.
- For the calculation of the intensity:
- if no weight is provided but the container info is, we assume the weight based on the container info.
- if none of the above is provided, we assume 10000 kg.
- CO₂ calculations are based on itineraries built from carrier services and their planned route.
- The
servicesparameter forces the routing engine to build itineraries that include the specified services. You can provide up to three service IDs. This is an "AND" condition, meaning the returned itinerary will include all specified services, even if the result is not the most optimal. If no feasible itinerary can be built using all the provided services, no results will be returned. - The
servicessequence matters: the order in which services are provided must match their natural sequence in the itinerary. If services are listed in an order that does not align with a possible route, the request may return no results. However, intermediate services not explicitly listed may still appear between the specified services when necessary to complete the itinerary. - In case of an itinerary with transhipments, the minimum CO₂ emissions value is the sum of the minimum values of each leg of the itinerary.
- Hashes are not intended to be persisted or used as permanent references.
Support endpoints and resources
- Understand how
weightandcontainerSizeTypeCodeimpact calculations across all transport modes: visit our Weight and Container Guide. - Retrieve maritime carriers: use our Carriers endpoint to search for carrier information based on SCAC codes or names.
- Retrieve service IDs: use our Search service by name endpoint.
- Find locations: access accurate data via our Geocoding endpoint.
- **Check the Supported Container size type codes for a complete list of accepted inputs.
- Learn about our methodology: visit the Methodology for sea emissions calculation page.