Get proformas and their CO₂e emissions for a carrier on a port pair.

get https://api.searoutes.com/itinerary/v2/proformas

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 GeoJSON FeatureCollection, where:

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