# Sea Route Distance and Shipping CO2 Emissions, Searoutes API (`nabeelbaghoor/sea-route-distance-co2-emissions-api`) Actor

Calculate sea route distance, voyage duration and ETA between ports, plus ISO 14083 and GLEC shipping CO2e emissions per shipment, carrier CO2e on a port pair, ocean schedules with CO2e, vessel ETA, port and carrier lookup through the Searoutes API. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/sea-route-distance-co2-emissions-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Developer tools, Business, Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 sea route calculateds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Sea Route Distance and Shipping CO2 Emissions, Searoutes API

Calculate sea route distances, voyage durations and ETAs between any ports, and ISO 14083 and GLEC compliant shipping CO2e emissions, through the Searoutes API with your own API key, as one clean dataset row per route, shipment, sailing, vessel, port or carrier.

Searoutes is a maritime routing and freight emissions platform used by shippers, forwarders and carriers for port to port distances, voyage planning and carbon reporting. This actor wraps its routing, emissions, schedule, vessel, geocoding and carrier endpoints on api.searoutes.com. Give it port pairs as UN/LOCODEs (CNSHA;NLRTM) or coordinates and get distance in kilometers and nautical miles, transit time, ETA, crossed canals and straits, ECA exposure, CO2e in kilograms with the well to tank and tank to wake split, and the emission intensity, ready to download as JSON, CSV or Excel, schedule, or feed into TMS, freight procurement, Scope 3 reporting, Google Sheets, BI dashboards and AI agents. Bring your own API key.

BYOK, not live tested: every path, parameter and enum comes from the OpenAPI definitions Searoutes publishes on developer.searoutes.com. The actor has not been run against a live Searoutes key.

### What it does

- **Sea route distance and ETA**: shortest navigable sea route between 2 to 20 ports or points, with distance in km and nautical miles, duration in hours, departure and arrival time, average speed, crossed canals and straits (Suez, Panama, Malacca, Gibraltar and the rest), distance inside ECA (SECA) zones and high risk areas, and the vessel used.
- **Route plan with waypoints**: the same route with every canal, strait and voyage entry and exit, its time and its distance from departure. Add the GeoJSON route line for maps.
- **Routing options**: vessel IMO, speed in knots, draft, departure date, avoid ECA zones, avoid piracy high risk areas, allow ice routes such as the Northern Sea Route, and block canals and straits such as the Suez Canal for Red Sea and Cape of Good Hope diversion scenarios.
- **Shipment CO2e emissions**: ISO 14083 and GLEC Framework emissions for FCL, LCL, parcel, bulk and breakbulk shipments over one or several sea legs, with carrier SCAC, vessel IMO, sea fuel (VLSFO, LNG, BIOLNG, methanol and more) and departure date, auto generated port hubs, a per leg and per hub breakdown, and an optional PDF emissions certificate.
- **Carrier CO2e on a port pair**: average, minimum and maximum CO2e of a carrier's itineraries between two ports, for carrier comparison and tender benchmarking.
- **Ocean schedules with CO2e**: upcoming sailings of a carrier on a port pair with departure, arrival, transit time, vessel, service, port calls and CO2e, sorted by lowest emissions or fastest transit.
- **Vessel ETA**: last AIS position, speed, destination port and the ETA from AIS and from Searoutes' predicted route, by IMO number.
- **Port and carrier lookup**: port UN/LOCODEs, country, size and ECA flag by name, and carrier SCACs and IDs by name.
- **Pay only for results**: refused and not found lookups are recorded as a free row that says why, never charged.

Nothing is written to your Searoutes account.

### How to use it

1. Get a Searoutes API key. Searoutes issues keys to its customers and hands out trial keys on request from developer.searoutes.com (the trial at the time of writing was 15 days or 300 calls, whichever ends first).
2. Paste the key into the API key field, or set the DATA_API_KEY environment secret. The key is sent only to api.searoutes.com in the x-api-key header and is removed from everything the actor logs.
3. Pick a mode, enter your routes or port pairs (one per line, such as CNSHA;NLRTM), set the options you need and run.
4. Download the dataset or connect it to your workflow through the Apify API, webhooks or integrations.

A missing or rejected key ends the run cleanly with a status message that explains what to change, and nothing is charged.

### Input

| Field | Modes | Description |
| --- | --- | --- |
| `mode` | all | `seaRoute` (default), `shipmentEmissions`, `carrierEmissions`, `oceanSchedules`, `vesselEta`, `portSearch` or `carrierSearch` |
| `routes` | route, shipment, carrier, schedules | One route per line: UN/LOCODEs or lon,lat pairs separated by `;`, such as `CNSHA;NLRTM` |
| `detailedPlan`, `includeGeometry` | sea route | Waypoints, and the GeoJSON route line |
| `vesselImo`, `departureDate` | sea route, shipment | 7 digit IMO and YYYY-MM-DD departure |
| `speedKnots`, `vesselDraft` | sea route | Speed in knots and draft in meters |
| `avoidSeca`, `avoidHighRiskAreas`, `allowIceAreas` | sea route | Routing constraints |
| `blockAreas` | sea route | Canals and straits to avoid, such as Suez Canal (11117) or Panama Canal (11112) |
| `carrier` | shipment, carrier, schedules | Carrier SCAC such as `CMDU` or `MSCU` (or a Searoutes carrier ID) |
| `orderType` | shipment | `FCL` (default), `LCL`, `parcel`, `bulk`, `breakbulk` |
| `containerCount`, `containerSizeTypeCode`, `cargoWeightKg` | shipment, carrier, schedules | Number of containers, ISO container code such as `40HC`, weight in kg |
| `fuelType`, `generateCertificate` | shipment | Sea fuel (needs the vessel IMO) and PDF certificate |
| `scheduleFromDate`, `scheduleToDate`, `sortBy` | schedules | Sailing window and `CO2` or `TRANSIT_TIME` order |
| `imos` | vessel ETA | One IMO number per line |
| `portQueries`, `portSizes`, `countryCodes`, `excludeCountryCodes` | port search | Names or UN/LOCODEs and filters |
| `carriers` | carrier search | Names or SCACs |
| `maxResults` | all | Row ceiling for the run (default 100) |
| `requestsPerMinute` | all | Pacing, default 60 |
| `apiKey` | all | Your Searoutes API key (or the DATA_API_KEY secret) |

Example: Shanghai to Rotterdam distance and ETA at 14 knots, avoiding the Suez Canal.

```json
{
    "mode": "seaRoute",
    "routes": ["CNSHA;NLRTM"],
    "speedKnots": 14,
    "departureDate": "2026-11-02",
    "blockAreas": ["11117"]
}
```

Example: ISO 14083 CO2e for two 40 foot high cube containers from Shanghai to Hamburg with CMA CGM.

```json
{
    "mode": "shipmentEmissions",
    "routes": ["CNSHA;DEHAM"],
    "carrier": "CMDU",
    "orderType": "FCL",
    "containerCount": 2,
    "containerSizeTypeCode": "40HC"
}
```

### Example output

An illustrative sea route row, shaped like the documented response (values are an example, not real data). The full Searoutes record is kept under `details`.

```json
{
    "mode": "seaRoute",
    "modeLabel": "Sea route distance and ETA",
    "recordType": "seaRoute",
    "query": "CNSHA;NLRTM",
    "found": true,
    "origin": "CNSHA",
    "destination": "NLRTM",
    "distanceKm": 19580.2,
    "distanceNm": 10572.4,
    "durationHours": 755.2,
    "departureTime": "2026-11-02T00:00:00.000Z",
    "arrivalTime": "2026-12-03T11:12:00.000Z",
    "speedKnots": 14,
    "secaDistanceKm": 1210.5,
    "hraDistanceKm": 0,
    "intersectsIceArea": false,
    "crossedAreas": ["Malacca Strait", "Suez Canal", "Gibraltar", "Dover Strait", "SECA Europe"],
    "vesselImo": null,
    "vesselName": null,
    "co2eTotalKg": null,
    "retrievedAt": "2026-10-23T12:00:00.000Z",
    "note": null,
    "details": { "distance": 19580200, "duration": 2718720000, "areas": { "type": "FeatureCollection", "features": ["..."] } }
}
```

A shipment row carries `co2eTotalKg`, `co2eWttKg`, `co2eTtwKg`, `co2eIntensity` (kg CO2e per tonne km), `distanceKm`, `legs` (each leg and hub with its mode, distance, model and CO2e) and `certificateUrl`. A carrier port pair row carries the average CO2e as `co2eTotalKg` plus `co2eMinKg`, `co2eMaxKg` and `itineraryCount`. A schedule row carries `departureTime`, `arrivalTime`, `durationHours`, `vesselName`, `serviceId`, `portCalls`, `itineraryHash` and `co2eTotalKg`. A vessel ETA row carries `latitude`, `longitude`, `speedKnots`, `destinationLocode`, `etaFromAis`, `etaPredicted` and `distanceToDestinationKm`. Port rows carry `locode`, `portName`, `countryCode`, `portSize` and `isSeca`; carrier rows carry `carrierName`, `carrierScac` and `carrierId`.

### Pricing

| Event | Price | Charged for |
| --- | --- | --- |
| `sea-route` | 0.01 USD | Each calculated sea route |
| `shipment-emissions` | 0.02 USD | Each ISO 14083 shipment CO2e report |
| `carrier-emissions` | 0.015 USD | Each carrier port pair CO2e statistic |
| `schedule-itinerary` | 0.01 USD | Each scheduled sailing |
| `vessel-eta` | 0.01 USD | Each vessel ETA |
| `reference-record` | 0.005 USD | Each port or carrier record |

Refused and not found lookups are never charged. Your Searoutes plan is billed separately by Searoutes.

### FAQ

#### What is the Searoutes API?

It is the API of Searoutes, a French maritime routing and freight emissions company. It calculates sea routes, distances and ETAs that follow traffic separation schemes, canals and port entries, and CO2e emissions for sea, air, road, rail and inland water freight under the GLEC Framework and ISO 14083, on api.searoutes.com.

#### How do I calculate the sea distance between two ports?

Choose Sea route distance and ETA and enter the two UN/LOCODEs separated by a semicolon, such as SGSIN;USLAX. Each row gives the distance in kilometers and nautical miles. Use Port search to find a port's UN/LOCODE from its name.

#### How do I calculate shipping CO2 emissions for a container shipment?

Choose Shipment CO2e emissions, enter the port pair, set the order type to FCL, the number of containers and the container type, and add the carrier SCAC and vessel IMO when you know them. The row gives total CO2e in kilograms, the well to tank and tank to wake split and the intensity, calculated under ISO 14083 and the GLEC Framework.

#### Can I model a Red Sea diversion around the Cape of Good Hope?

Yes. In Sea route mode, block the Suez Canal (11117) and compare the distance, duration and crossed areas with the unblocked route.

#### Does it support multimodal shipments?

The Searoutes Shipment API covers sea, road, rail, air and inland water legs. This actor sends sea legs, one per pair of stops on a line, and the API adds port hubs automatically.

#### Which carrier has the lowest CO2e on my trade lane?

Run Carrier port pair CO2e for each carrier SCAC on the same port pair, or Ocean schedules with CO2e sorted by CO2 to compare actual upcoming sailings.

#### How many API calls does a run use?

One per route, shipment, port pair, IMO number, port query or carrier query. The run log reports the exact request count.

#### Do I need my own Searoutes API key?

Yes. This is a bring your own key actor: it calls Searoutes with your key, under your plan and your agreement with Searoutes.

### Keyword map

Sea route distance calculator, port to port distance API, nautical miles between ports, shipping route API, voyage ETA calculator, vessel ETA API, shipping CO2 calculator, freight emissions API, ISO 14083 emissions API, GLEC Framework calculator, container shipping carbon footprint, Scope 3 transport emissions, ocean schedules API, carrier emissions comparison, Suez Canal diversion distance, ECA SECA distance, UN/LOCODE port search, SCAC carrier lookup, Searoutes API.

### Licensing and data use

Searoutes data is used here under your own Searoutes subscription. Its Terms of Service (last updated 17 February 2026) require a signed agreement, limit use to the purpose disclosed to Searoutes (such as supply chain optimisation and carbon reporting), and allow the client to share, sell, sub-license or distribute Searoutes information to parties it has a commercial relationship with, except companies that compete with Searoutes. Keep the results within the uses your agreement allows. This actor is not affiliated with or endorsed by Searoutes.

# Actor input Schema

## `mode` (type: `string`):

Sea route distance and ETA: GET /route/v2/sea, one row per route with distance in km and nautical miles, duration, ETA, crossed canals and straits, ECA (SECA) and high risk area distance. Shipment CO2e emissions: POST /shipment/v2/report/co2 (ISO 14083, GLEC), one row per shipment. Carrier port pair CO2e: GET /co2/v2/plan, one row of statistics per port pair. Ocean schedules with CO2e: GET /itinerary/v2/execution, one row per upcoming sailing. Vessel ETA: GET /vessel/v2/{imo}/eta. Port search and Carrier search: reference lookups. Each lookup is one call on your Searoutes plan.

## `routes` (type: `array`):

Sea route, shipment, carrier and schedule modes. One route per line as UN/LOCODEs or lon,lat pairs separated by ";", such as CNSHA;NLRTM, SGSIN;USLAX or 121.8,31.2;4.0,51.9. Sea routes take up to 20 stops; shipments turn each pair of stops into a sea leg; carrier and schedule modes take exactly two UN/LOCODEs.

## `detailedPlan` (type: `boolean`):

Sea route only. Uses GET /route/v2/sea/{locations}/plan, which adds the waypoints (canal, strait and voyage entries and exits with times and distances) to each route.

## `includeGeometry` (type: `boolean`):

Sea route only. Adds the GeoJSON LineString of the route to each row, ready for a map. Off by default to keep rows small.

## `vesselImo` (type: `string`):

Sea route and shipment modes, optional. The 7 digit IMO number of the vessel, such as 9776418. Routes then use its draft and speed; shipment emissions use its own profile and fuel.

## `speedKnots` (type: `number`):

Sea route only, optional. Vessel speed in knots (sent as speedInKts), used for the duration and ETA.

## `vesselDraft` (type: `number`):

Sea route only, optional. Vessel draft in meters, so shallow passages are avoided.

## `departureDate` (type: `string`):

Sea route and shipment modes, optional. YYYY-MM-DD. Sea routes return the ETA from this departure; shipments send it as the first leg departure date.

## `avoidSeca` (type: `boolean`):

Sea route only. Routes around sulphur emission control areas where possible (avoidSeca).

## `avoidHighRiskAreas` (type: `boolean`):

Sea route only. Routes around piracy high risk areas (avoidHRA).

## `allowIceAreas` (type: `boolean`):

Sea route only. Allows routes through ice areas such as the Northern Sea Route and the Bering Sea (allowIceAreas).

## `blockAreas` (type: `array`):

Sea route only. Canals and straits the route must not pass, such as the Suez Canal or the Panama Canal (blockAreas). Useful for Red Sea and Cape of Good Hope diversions.

## `carrier` (type: `string`):

Shipment, carrier and schedule modes. The carrier SCAC, such as CMDU, MSCU or MAEU (or a Searoutes carrier ID for carrier and schedule modes). Required for carrier and schedule modes; the Carrier search mode finds it from a name.

## `orderType` (type: `string`):

Shipment only. FCL needs the number of containers; every other type needs the cargo weight.

## `containerCount` (type: `integer`):

Shipment, carrier and schedule modes. Number of containers shipped (nContainers).

## `containerSizeTypeCode` (type: `string`):

Shipment, carrier and schedule modes, optional. ISO container size type code such as 20GP, 40GP, 40HC or 45R1 (reefer). Searoutes defaults to 20GP.

## `cargoWeightKg` (type: `number`):

Shipment, carrier and schedule modes. Weight of the goods in kilograms. Required for LCL, parcel, bulk and breakbulk shipments.

## `fuelType` (type: `string`):

Shipment only, optional. Sea fuel such as VLSFO, LNG, BIOLNG or METHANOL for fuel switch scenarios. Searoutes applies it only when the vessel IMO is set; without it the vessel's least green fuel is assumed.

## `generateCertificate` (type: `boolean`):

Shipment only. Asks Searoutes for a PDF emissions certificate per shipment; its link is returned as certificateUrl.

## `scheduleFromDate` (type: `string`):

Ocean schedules only, optional. Earliest sailing date, YYYY-MM-DD.

## `scheduleToDate` (type: `string`):

Ocean schedules only, optional. Latest sailing date, YYYY-MM-DD.

## `sortBy` (type: `string`):

Ocean schedules only, optional. Searoutes sorts by CO2e when not set.

## `imos` (type: `array`):

Vessel ETA only. One 7 digit IMO number per line. Returns the last AIS position, speed, destination and the ETA from AIS and from the predicted route.

## `portQueries` (type: `array`):

Port search only. One port name or UN/LOCODE per line, such as Rotterdam or NLRTM. A UN/LOCODE in capitals is an exact lookup.

## `portSizes` (type: `array`):

Port search only, optional. Keeps ports of these sizes.

## `countryCodes` (type: `array`):

Port search only, optional. Two letter ISO country codes to keep, such as NL or SG.

## `excludeCountryCodes` (type: `array`):

Port search only, optional. Two letter ISO country codes to leave out.

## `carriers` (type: `array`):

Carrier search only. One carrier name, partial name or 4 letter SCAC per line, such as Maersk, CMA CGM or MSCU.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for.

## `requestsPerMinute` (type: `integer`):

Pacing for calls to api.searoutes.com. Your Searoutes usage plan sets the real ceiling.

## `apiKey` (type: `string`):

Your own Searoutes API key. Stored as a secret and sent only to api.searoutes.com in the x-api-key header; it is never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "seaRoute",
  "routes": [
    "CNSHA;NLRTM"
  ],
  "detailedPlan": false,
  "includeGeometry": false,
  "avoidSeca": false,
  "avoidHighRiskAreas": false,
  "allowIceAreas": false,
  "orderType": "FCL",
  "containerCount": 1,
  "generateCertificate": false,
  "maxResults": 100,
  "requestsPerMinute": 60
}
```

# Actor output Schema

## `records` (type: `string`):

One row per route, shipment, port pair statistic, sailing, vessel, port or carrier.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "routes": [
        "CNSHA;NLRTM"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/sea-route-distance-co2-emissions-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "routes": ["CNSHA;NLRTM"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/sea-route-distance-co2-emissions-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "routes": [
    "CNSHA;NLRTM"
  ]
}' |
apify call nabeelbaghoor/sea-route-distance-co2-emissions-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/sea-route-distance-co2-emissions-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/kAtgW2XRSsknRAval/builds/hcQclVEx1nsWxacZe/openapi.json