Sign in

v1

latestOpenAPI 3.1.02026-07-243613262.4 KB
Schedules

Get ocean schedules and their CO₂e emissions for a port pair

Gain the ability to choose the greenest or fastest option among upcoming vessel departures, selecting from the best available itineraries per carrier. This endpoint returns the possible itinerary and their CO₂e emissions in the near future, for a given carrier and a given port pair. The CO₂e emissions are returned in grams.

Input

Location of origin (fromLocode) and destination (toLocode), and carrier information (carrierScac or carrierId) are mandatory fields.

Dates

This endpoint takes two dates as input: fromDate and toDate. It represents the departure date range within which the endpoint will search for itineraries. Passing the dates is optional. If no date is given, the endpoint will return itineraries sailing 7 days onwards after the current date. Both dates should be passed using the ISO 8601 format.

Sorting

To get the results in order of preference, use the parameter sortBy. You can input CO2 or TRANSIT_TIME, depending on your main interest.

Response

The response is a list of featureCollection's, where each feature collection is a possible itinerary.

The feature collection is made of:

  • One or multiple features A direct itinerary results in a feature collection made of only one feature. An itinerary with transshipments results is a feature collection made of multiple features, each of it representing one leg.
  • One hash Each itinerary is associated to a unique fingerprint (called "hash") that you can use to retrieve the CO₂e breakdown and details of the itinerary via the /co2/v2/execution endpoint. It will return the CO₂e breakdown (total, TTW, WTT, intensity values).

Each feature has its own properties, including details such as duration, departure and arrival dates, locations, distance, mode, service ID, asset (vessel) details, port of calls, total CO₂e emissions.

Results are given in the order of sorting requested (CO2 or TRANSIT_TIME). If no sortBy is input, the sorting will be done on the CO₂e basis.

Notes & considerations

  • Hashes are not intended to be persisted or used as permanent references.

Support endpoints and resources

  • Get CO₂e emissions for a given ocean schedule itinerary (by hash): use our /co2/v2/execution/{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 locations: access accurate data via our Geocoding endpoint.
  • Explore the list of Supported fields and values.
get/itinerary/v2/execution

Query parameters

fromLocodestring required
Example:BRSSZ

The UNLOCODE of the departure port.

toLocodestring required
Example:COCTG

The UNLOCODE of the arrival port.

carrierScacstring
Example:CMDU

The Standard Carrier Alpha Code (SCAC) of the carrier. Note that you must provide either a SCAC or a carrier id.

carrierIdnumber
Example:21

The id of the carrier (can be found via the search endpoints). Note that you must provide either a SCAC or a carrier id.

fromDatestring
Example:2023-12-07T15:00:00Z

Specifies the sailing date from which the itineraries are retrieved, in the ISO 8601 format.

toDatestring
Example:2023-12-25T15:00:00Z

Specifies the sailing date until which the itineraries are retrieved, in the ISO 8601 format.

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:5000

The weight of the shipped goods in kilograms.

sortBystring
Example:CO2

Defines the sorting of the itinerary results, whether by CO2 or TRANSIT_TIME. By default, results will be sorted by CO2.

Response

OK