API Reference
Complete reference for the Searoutesnav REST API. The base URL for all requests is https://api.searoutesnav.com. All endpoints return JSON. Authenticated endpoints require a bearer token obtained from POST /auth/login. See Authentication.
Authentication
Authenticate with email and password and receive a bearer token.
Response 200
Returns 401 on invalid credentials.
Revoke the bearer token used for the request.
Return the profile of the currently authenticated user.
Response 200
Return today's query usage and the remaining daily quota for the authenticated user.
Email a new password to the account (requires SMTP configured on the server).
Routing
Calculate a sea route between two points, given either coordinates or port ids. Throttled against your daily query limit. Each origin/destination is supplied as either { "coordinates": [lon, lat] } or { "port_id": 123 }.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| origin | object | Yes | coordinates [lon, lat] or port_id |
| destination | object | Yes | coordinates [lon, lat] or port_id |
| speed_kmh | number | No | Vessel speed for duration estimates |
| resolution_km | enum | No | Grid resolution: 5, 10, 20, 50, 100 |
| suez / panama / gibraltar / kiel | boolean | No | Allow/forbid passage through each strait/canal |
| include_ports | boolean | No | Include intermediate ports in the response |
| waypoint_count | integer | No | Target number of returned waypoints |
| waypoint_strategy | enum | No | Waypoint sampling: 'nth', 'count', 'simplify', 'none' |
| vessel | object | No | type (container|bulker|tanker, required), size_class, draft_m, beam_m, loa_m, fuel_tonnes_per_day, fuel_type (HFO|VLSFO|MGO) |
| fuel_price_usd_per_tonne | number | No | Used for cost estimates in the emissions block |
Example request
Response 200
Errors: 401 unauthenticated, 404 port not found, 429 daily query limit exceeded.
Compute an origins × destinations distance/duration matrix. Each cell counts as one query against your daily budget; the matrix is capped at 10,000 cells.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| origins | array | Yes | List of { coordinates } or { port_id } |
| destinations | array | Yes | List of { coordinates } or { port_id } |
| speed_kmh | number | No | Vessel speed for duration estimates |
| resolution_km | enum | No | Grid resolution: 5, 10, 20, 50, 100 |
| suez / panama / gibraltar | boolean | No | Allow/forbid each strait/canal |
| vessel | object | No | Same shape as /calculate-route |
| fuel_price_usd_per_tonne | number | No | Used for cost estimates |
Response 200
Errors: 422 empty/oversized matrix, 429 exceeds remaining daily budget.
Fetch a saved port-to-port route by its SEO slug.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| slug | string | Yes | Route slug, e.g. new-york-to-london |
Returns 404 if the slug is unknown.
Return a set of example route requests useful for getting started.
Return the authenticated caller's most recent route calculations.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer | No | Maximum number of entries to return |
Ports
Autocomplete port names for use as route origins/destinations.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
| q | string | Yes | Search term (port name prefix) |
| limit | integer | No | Maximum number of results |
Response 200
Emissions
Estimate GLEC-aligned (ISO 14083) well-to-wake greenhouse-gas emissions for a navigable sea route. The route is derived from the origin/destination the same way as /calculate-route. Counts against your daily query limit.
Request body
| Name | Type | Required | Description |
|---|---|---|---|
| route | object | Yes | origin & destination, each as { "port_id": 123 } or { "lat": .., "lon": .. }; optional avoid[] (seca, piracy, suez, panama, gibraltar, malacca, dover, bering, magellan, babelmandeb, kiel, corinth, northwest, northeast) and resolution_km |
| cargo | object | No | teu (> 0) for containers, or mass_tonnes (> 0) otherwise; container_type, reefer (default false) |
| vessel | object | No | type (container|feeder_container|deep_sea_container|dry_bulk|tanker|general_cargo|ro_ro|vehicle_carrier|ferry); optional imo, name, capacity_teu, deadweight_tonnes, fuel_type |
| fuel | object | No | consumed_tonnes (> 0) and type (HFO|VLSFO|MGO|MDO). Supplying it enables the fuel-based method |
| calculation | object | No | method (auto|fuel_based|activity_based|carrier_intensity|default_maritime, default auto), boundary (TTW|WTT|WTW, default WTW) |
| framework | object | No | name (default "GLEC"), version (default "3.0") |
| carrier | object | No | Optional carrier { code, name } for carrier-intensity factors |
Example request
Response 200
Errors: 401 unauthenticated, 404 no compatible emission factor, 422 validation error, 429 daily limit exceeded, 503 emissions service not initialized.
Dry-run an emissions request: validate the inputs and preview which method, factor and boundary would be used, without running the calculation or consuming any quota. Accepts the same body as /v1/emissions/sea.
Response 200
Errors: 401 unauthenticated, 422 undecodable JSON, 503 emissions service not initialized.
Statistics
Return aggregate route metrics.
Return route cache and deduplication metrics.