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