Search routes (beta)

🧪

Beta notice

This endpoint is part of our Ocean Schedules beta testing phase.
Please note that:

• The behavior and structure may change before public release.
• Some features or results may still be incomplete or evolving.

This endpoint generates a new route snapshot based on the provided input (type, origin, destination, mode, departure date, etc.)
Detailed request fields are documented in the body parameters below.
You can search for routes of different types:

• shortest → shortest feasible path, considering traffic separation schemes and port entries.
• historical → reconstructs past voyages around the given departureDate using AIS data.
• proforma → based on carriers service plans.
• schedule → based on upcoming carrier vessel departures.

The response will be a JSON array containing details of the created route, including the object id, type, from and to locations, departure and arrival details, duration, carriers, distance, legs, and asset information.
These route snapshots are read-only and can be used via their id with sub-resources like /geometry, /fuel, or /emission.

Notes and considerations

• id lifetime: the route id remains valid for a limited period (at least 1 hour).

Support endpoints and resources

• Get routes: use the /v3/routes endpoint to retrieve route snapshots (id) and their details.
• Retrieve maritime carriers: use our Carriers endpoint to search carriers by SCAC or name.
• Find locations: use our Geocoding endpoint for location codes.