v1
latestOpenAPI 3.1.02026-07-243613262.4 KBProformas
Get proformas and their CO₂e emissions for a carrier on a port pair.
This endpoint retrieves itineraries for a given carrier on a given port pair. It provides estimated transit times, distance and route details, along with CO₂e data.
Response
The response is a list of FeatureCollection, where:
- Each featureCollection represents an itinerary.
- Properties contain key details such as transit time, CO₂ emissions, and ports of call.
- Geometry provides the route geometry as a LineString in GeoJSON format.
| Field | Description |
|---|---|
| duration.days | Estimated transit time in days, including transhipments and waiting time in ports. |
| duration.ms | Estimated transit time in milliseconds. |
| departure.dayNumber | Represents the starting reference day of the journey. |
| arrival.dayNumber | Represents the arrival day relative to the departure day. |
| from.locode | Departure port UN/LOCODE. |
| from.name | Departure port name. |
| to.locode | Arrival port UN/LOCODE. |
| to.name | Arrival port name. |
| distance | Total itinerary distance (in meters). |
| mode | Transport mode ("SEA"). |
| serviceId | Service ID associated with the leg. Retrievable with /search/v2/service/{id} |
| calls | List of intermediate port calls. |
| co2e | Estimated CO₂ emissions for the itinerary. |
| geometry | GeoJSON LineString representing the leg’s route geometry. |
Notes & considerations
- GeoJSON compliance: by default, the response includes a properties field at the FeatureCollection level. If full GeoJSON compliance is required, you should omit properties field.
- The services parameter 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 services sequence 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.
- Sorting behavior:
- TRANSIT_TIME: Returns fastest itineraries first.
- CO2: Returns itineraries with the lowest estimated CO₂ emissions first.
- Each itinerary has a unique hash, which can be used to retrieve additional CO₂ details from /co2/v2/proformas/{hash}.
- Proforma API itineraries vs. Execution API itineraries:
- /itinerary/v2/proformas provides planned itineraries for strategic procurement and short to long-term support to decision-making.
- /itinerary/v2/execution data (from /itinerary/v2/execution) reflects upcoming departures, including sailing dates and assigned vessels, for optimizing immediate shipments' operations.
- Hashes are not intended to be persisted or used as permanent references.
Support endpoints and resources
- ** Retrieve CO₂e details for an itinerary** using the /co2/v2/proformas/{hash} endpoint
- Learn about our methodology: visit the Methodology for sea emissions calculation page.
- Understand how weight and containerSizeTypeCode impact 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.
- Find services ids by name: using our Search endpoint.
- Find locations: access accurate data via our Geocoding endpoint.
- Explore the list of Supported fields and values.
get/itinerary/v2/proformas
Query parameters
fromLocodestring required
Example:CNSHA
The UNLOCODE of the departure port.
toLocodestring required
Example:FRLEH
The UNLOCODE of the arrival port.
carrierIdnumber
Example:21
The ID of the carrier (can be found via the search endpoints). Either a SCAC or a carrier ID must be provided.
carrierScacstring
Example:CMDU
The Standard Carrier Alpha Code (SCAC) of the carrier. Either a SCAC or a carrier ID must be provided.
servicesnumber
Example:1961
The ID of the service(s) (up to three) that must be included in the itinerary.
nContainersnumber
Example:1
The number of shipped containers.
containerSizeTypeCodestring
Example:20GP
Code to identify the size and the type of the container (e.g., 20GP).
weightinteger
Example:10000
The weight of the shipped goods in kilograms.
sortBystring
Example:TRANSIT_TIME
Defines sorting criteria for the results, whether by CO2 or TRANSIT_TIME.
Response
OK