# Vessel Tracking API - MarineTraffic AIS Ship Positions, Ports (`nabeelbaghoor/vessel-tracking-ais-ship-position-api`) Actor

AIS vessel tracking from the MarineTraffic API (Kpler): live ship positions by IMO or MMSI, fleet and area positions, historical tracks, port calls, expected port arrivals, voyage forecasts with ETA, vessel search and ship particulars. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/vessel-tracking-ais-ship-position-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 $5.00 / 1,000 vessel position or track point returneds

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

## Vessel Tracking API - MarineTraffic AIS Ship Positions, Ports

Track ships with the MarineTraffic AIS Data API (Kpler) using your own service key, and get live vessel positions, fleet and area positions, historical tracks, port calls, expected port arrivals, voyage forecasts with ETA, vessel search and ship particulars as clean dataset rows.

Works with the official MarineTraffic AIS API on services.marinetraffic.com, documented at servicedocs.marinetraffic.com. The actor turns IMO numbers, MMSI numbers, ports or vessel names into deduplicated rows you can download as JSON, CSV or Excel, schedule, or feed into fleet dashboards, supply chain visibility, freight and commodity analytics, port operations, Google Sheets and AI agents. Bring your own API key.

BYOK, not live-tested: every service, version, parameter and field comes from the OpenAPI document behind MarineTraffic's published API reference, and every route was confirmed to exist on services.marinetraffic.com (an invalid key gets "SERVICE KEY NOT FOUND", not a missing route), but the actor has not been run against a live MarineTraffic subscription.

### What it does

- **Latest vessel position by IMO or MMSI**: the current AIS position of each vessel, with latitude, longitude, speed, course, heading, navigational status, terrestrial or satellite source, plus voyage data: destination, reported and calculated ETA, last, current and next port, draught, distance travelled and to go, and ship type, flag, size and DWT.
- **Positions of your MarineTraffic fleet**: every vessel in the fleet on your MarineTraffic account, paged with the documented cursor, filterable by vessel type.
- **Positions in your area of interest**: every vessel inside the area of interest set up for your key.
- **Historical vessel track**: past AIS positions of a vessel for up to 190 days at a time, back to January 2015, every position or one per hour or day, optionally with wind, wave, swell and current weather.
- **Port calls by port or vessel**: arrivals and departures at a port (MarineTraffic port ID or UN/LOCODE) or of a vessel, with local and UTC times, filterable by arrivals or departures, transit, DWT and GT, optionally with draught, load status and voyage statistics.
- **Expected arrivals at a port**: vessels heading to a port in the next 40 days, or currently in port, with ETA, position and optional particulars, filterable by previous port, ship type and size.
- **Voyage forecast and ETA by vessel**: destination, last port, next port and ETA (reported and MarineTraffic calculated), optionally with distances, load condition and the predicted route.
- **Vessel search by name or identifier**: find ships by name (up to 100 matches, exact first) or by IMO or MMSI, with call sign, type, flag, DWT, build year and MarineTraffic link.
- **Vessel particulars by IMO or MMSI**: builder, build year, dimensions, DWT, gross and net tonnage, TEU, owner, manager, financial owner, technical manager and insurer, optionally with engine, class society and hull data.
- **Pay only for results**: refused and empty lookups are recorded as a free row that says why, never charged.

### How to get an API key

MarineTraffic sells API access per service (Vessel Positions, Historical Track, Port Calls, Expected Arrivals, Voyage Forecast, Search Vessel, Vessel Particulars and so on). Request the service you need from MarineTraffic (a Kpler company) through marinetraffic.com or your Kpler account manager. Once it is active, open the API Services page of your marinetraffic.com account and copy the 40 character key of that service. Paste it into the API key field, or set the DATA_API_KEY secret. Every service has its own key, so pick the mode that matches the key you paste. The MarineTraffic API takes the key as part of the URL path; this actor sends it only to services.marinetraffic.com and never logs it.

### Input

| Field | Modes | Description |
| --- | --- | --- |
| `mode` | all | `vesselPosition`, `fleetPositions`, `areaPositions`, `vesselTrack`, `portCalls`, `expectedArrivals`, `voyageForecast`, `vesselSearch` or `vesselParticulars` |
| `vessels` | vessel modes, port calls, vessel search | IMO 9241061, MMSI 310627000, shipid 371681, bare IMO or MMSI numbers, or MarineTraffic vessel URLs |
| `vesselNames` | vessel search | Vessel names, at least 3 characters |
| `ports` | port calls, expected arrivals | MarineTraffic port IDs such as 1766; port calls also take UN/LOCODEs such as NLAMS |
| `timespan` | position modes, port calls | Minutes back: up to 1440 for positions (default 60), up to 2880 for port calls (default 1440) |
| `days` | historical track | Days back, up to 190 (default 1) |
| `fromDate`, `toDate` | track, port calls, expected arrivals | YYYY-MM-DD or YYYY-MM-DD HH:MM in UTC, at most 190 days apart |
| `daysAhead` | expected arrivals | Up to 40 days ahead; empty means vessels currently in port |
| `trackPeriod` | historical track | Every position, hourly or daily |
| `moveType`, `excludeInTransit` | port calls | Arrivals, departures or both; skip vessels in transit |
| `shipType` | expected arrivals, vessel search | Fishing, High speed craft, Passenger, Cargo or Tanker |
| `vesselTypeIds` | fleet and area positions | MarineTraffic vessel type IDs |
| `fromPort` | expected arrivals | Previous port ID or UN/LOCODE |
| `dwtMin`, `dwtMax`, `gtMin`, `gtMax` | port calls, expected arrivals | Size filters |
| `extended` | track, port calls, arrivals, forecast, particulars | MarineTraffic extended response |
| `maxResults` | all | Row ceiling for the run (default 100) |
| `requestsPerMinute` | all | Pacing, default 6 |
| `apiKey` | all | Your MarineTraffic service key (or the DATA_API_KEY secret) |

Example: the latest position of two ships.

```json
{
    "mode": "vesselPosition",
    "vessels": ["IMO 9241061", "MMSI 244740452"],
    "timespan": 120
}
```

Example: arrivals and departures at Amsterdam over one week.

```json
{
    "mode": "portCalls",
    "ports": ["1766"],
    "fromDate": "2026-10-01",
    "toDate": "2026-10-08",
    "excludeInTransit": true
}
```

### Example output

An illustrative latest position row, shaped like MarineTraffic's documented Single Vessel Positions response (values are an example, not real data). Every field MarineTraffic returns is kept; only some are shown.

```json
{
    "mode": "vesselPosition",
    "recordType": "position",
    "identifier": "IMO 9241061",
    "found": true,
    "shipName": "QUEEN MARY 2",
    "imo": "9241061",
    "mmsi": "310627000",
    "shipId": "371681",
    "vesselType": "Passenger",
    "flag": "BM",
    "latitude": 50.12345,
    "longitude": -3.45678,
    "speedKnots": 18.4,
    "course": 245,
    "heading": 244,
    "navStatus": "0",
    "positionTime": "2026-10-15T09:41:12",
    "destination": "NEW YORK",
    "eta": "2026-10-21T06:00:00",
    "portName": null,
    "MMSI": "310627000",
    "IMO": "9241061",
    "SHIP_ID": "371681",
    "LAT": "50.123450",
    "LON": "-3.456780",
    "SPEED": "184",
    "DSRC": "SAT",
    "LAST_PORT": "SOUTHAMPTON",
    "LAST_PORT_UNLOCODE": "GBSOU",
    "NEXT_PORT_NAME": "NEW YORK",
    "DISTANCE_TO_GO": "2911",
    "retrievedAt": "2026-10-15T09:45:00.000Z",
    "note": null
}
```

### FAQ

#### What is the MarineTraffic AIS API?

MarineTraffic, part of Kpler since 2023, runs one of the largest AIS vessel tracking networks, combining terrestrial and satellite AIS receivers. Its AIS Data API on services.marinetraffic.com serves vessel positions, historical tracks, port calls, expected arrivals, voyage forecasts, vessel search and vessel particulars, each as a separately licensed service with its own key.

#### Do I need my own MarineTraffic key?

Yes. This is a bring-your-own-key actor: it calls MarineTraffic with your key, under your MarineTraffic contract and terms. A missing, rejected, expired or exhausted key ends the run cleanly with a status message that explains what to change, and nothing is charged.

#### Why does my key work in one mode and not another?

MarineTraffic issues one key per API service. A Vessel Positions key answers "SERVICE KEY DOES NOT MATCH SERVICE TYPE" on Port Calls. Pick the mode that matches the service the key belongs to.

#### How do I find a vessel's IMO, MMSI or MarineTraffic ship ID?

Use Vessel search with the vessel name. Each match carries the IMO number, MMSI, MarineTraffic ship ID, call sign and a link to its MarineTraffic page. You can also paste a MarineTraffic vessel page URL into the vessels input.

#### How do I find a MarineTraffic port ID?

Open the port page on marinetraffic.com: the number in its URL is the port ID (1766 is Amsterdam). Port calls also accept the UN/LOCODE, such as NLAMS.

#### How far back does vessel history go?

Historical tracks and port calls go back to January 2015, with up to 190 days per request. Weather on tracks is available from 2015 for wind and from 2021 for waves, swell and currents.

#### What does speed mean in the rows?

MarineTraffic reports SPEED in knots times ten. The speedKnots column divides it by ten, and the raw SPEED field is kept. A heading of 511 or -1 means no heading and becomes null in the heading column.

#### What do I pay?

Pay per result: 0.005 USD per vessel position or track point, and 0.01 USD per port call, expected arrival, voyage forecast, vessel search match or vessel particulars record. Refused and empty lookups are never charged. Your MarineTraffic service is billed separately by MarineTraffic, under a contract that sets how many calls each key may make per period.

#### What happens if my key is wrong or my call limit runs out?

"SERVICE KEY NOT FOUND" or "INVALID KEY" ends the run cleanly. "SERVICE EXPIRED", "SERVICE INACTIVE", "IP NOT ALLOWED" and a key for another service do the same with MarineTraffic's own words. "ABOVE SERVICE CALL LIMIT" and "TOO MANY REQUESTS" are waited out and retried, and a call limit that stays used up ends the run cleanly. A vessel, port or date MarineTraffic refuses becomes a free row with the API's message, and the run moves on.

### Pricing

| Event | Price | Charged for |
| --- | --- | --- |
| `vessel-position` | 0.005 USD | Each vessel position or historical track point |
| `voyage-event` | 0.01 USD | Each port call, expected arrival or voyage forecast |
| `vessel-record` | 0.01 USD | Each vessel search match or vessel particulars record |

### Keyword map

vessel tracking API, ship tracking API, AIS API, MarineTraffic API, Kpler AIS, live ship position, vessel position by IMO, MMSI lookup, fleet tracking, ship location, historical vessel track, AIS history, port calls API, vessel arrivals and departures, expected port arrivals, vessel ETA, voyage forecast, ship search, vessel particulars, ship owner and manager, maritime data API.

### Terms and data use

MarineTraffic data is licensed by Kpler under your MarineTraffic API contract, which governs what you may do with it. Kpler's public Terms of Use (kpler.com/company/terms-of-use) allow display, derived data and internal distribution "solely for research and internal business purposes", and, except as Kpler agrees in writing, forbid reselling, sublicensing or publishing the data, making it available to anyone not entitled to it, "mirroring" it on another server, and using it in financial products, indices or advertising. They also require deleting the data when your agreement ends. Run this actor only with your own key and only if your MarineTraffic contract allows keeping the results in your own Apify storage; keep the results for your own internal use and delete them when your agreement ends. Contact Kpler before republishing or reselling the data. This actor is not affiliated with or endorsed by MarineTraffic or Kpler.

# Actor input Schema

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

Each mode calls one MarineTraffic API service, and every service has its own key: use the key of the service you subscribed to. Latest vessel position reads the current AIS position and voyage of each vessel. Fleet and area positions read every vessel in the fleet or area of interest set up on your MarineTraffic account. Historical track reads past positions. Port calls reads arrivals and departures at a port or of a vessel. Expected arrivals reads vessels heading to a port. Voyage forecast reads destination and ETA. Vessel search finds vessels by name or identifier. Vessel particulars reads ship details, owner and manager.

## `vessels` (type: `array`):

Vessel modes, plus port calls and vessel search. One vessel per line: IMO 9241061, MMSI 310627000, shipid 371681 (the MarineTraffic ship ID), a bare 7 digit IMO or 9 digit MMSI number, or a MarineTraffic vessel page URL.

## `vesselNames` (type: `array`):

Vessel search only. Full or partial vessel names, at least 3 characters each. MarineTraffic returns up to 100 active vessels per name, exact matches first.

## `ports` (type: `array`):

Port calls and Expected arrivals. MarineTraffic port IDs (the number in the port page URL on marinetraffic.com, such as 1766 for Amsterdam). Port calls also take UN/LOCODEs such as NLAMS.

## `timespan` (type: `integer`):

Position modes: how far back to look for each vessel's latest position, up to 1440 minutes (empty means 60). Port calls without dates: the maximum age of the calls, up to 2880 minutes (empty means 1440, the last 24 hours).

## `days` (type: `integer`):

Historical track only. Days back from now to read positions for, up to 190. Ignored when a from and to date are given. Empty means 1.

## `fromDate` (type: `string`):

Historical track, Port calls and Expected arrivals. Start of the window as YYYY-MM-DD or YYYY-MM-DD HH:MM in UTC. Set together with the to date; at most 190 days apart. Tracks and port calls go back to January 2015; expected arrivals look forward.

## `toDate` (type: `string`):

End of the window, in the same format as the from date.

## `daysAhead` (type: `integer`):

Expected arrivals only. Days into the future to look for expected arrivals, up to 40. Leave this and the dates empty to get the vessels currently in port.

## `trackPeriod` (type: `string`):

Historical track only. Hourly and daily keep the first position received in each hour or day, which keeps long tracks small.

## `moveType` (type: `string`):

Port calls only.

## `excludeInTransit` (type: `boolean`):

Port calls only. Leave out vessels that only passed through the port.

## `shipType` (type: `string`):

Expected arrivals and Vessel search. Leave empty for all types.

## `vesselTypeIds` (type: `array`):

Fleet and area positions only. MarineTraffic vessel type IDs to keep (see the MarineTraffic ship types article). Leave empty for all vessels.

## `fromPort` (type: `string`):

Expected arrivals only. Only vessels coming from this port: a MarineTraffic port ID such as 106, or a UN/LOCODE such as GBSOU.

## `dwtMin` (type: `integer`):

Port calls and Expected arrivals. Minimum deadweight tonnage (IMO registered vessels). Expected arrivals need the minimum and maximum together.

## `dwtMax` (type: `integer`):

Port calls and Expected arrivals. Maximum deadweight tonnage.

## `gtMin` (type: `integer`):

Port calls and Expected arrivals. Minimum gross tonnage (IMO registered vessels). Expected arrivals need the minimum and maximum together.

## `gtMax` (type: `integer`):

Port calls and Expected arrivals. Maximum gross tonnage.

## `extended` (type: `boolean`):

Historical track (adds wind, wave, swell and current weather), Port calls (adds draught, load status and voyage data since the previous call), Expected arrivals (adds vessel particulars), Voyage forecast (adds distances, load condition and route) and Vessel particulars (adds engine, class, hull and owner contact details). Your service must include the extended response, and MarineTraffic often allows fewer extended calls.

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

The most rows this run returns and charges for.

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

Pacing. Your MarineTraffic contract sets how many calls each service key may make per period (often only a few per minute), and every key is capped at 100 calls a minute. A call limit answer is waited out and retried.

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

Your own MarineTraffic service key (40 hexadecimal characters) for the service this mode reads, from the API Services page of your marinetraffic.com account. Stored as a secret and sent only to services.marinetraffic.com, in the URL path the API requires; it is never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "vesselPosition",
  "vessels": [
    "IMO 9241061"
  ],
  "trackPeriod": "all",
  "moveType": "both",
  "excludeInTransit": false,
  "extended": false,
  "maxResults": 100,
  "requestsPerMinute": 6
}
```

# Actor output Schema

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

One row per position, track point, port call, expected arrival, voyage forecast or vessel.

# 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 = {
    "vessels": [
        "IMO 9241061"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/vessel-tracking-ais-ship-position-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 = { "vessels": ["IMO 9241061"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/vessel-tracking-ais-ship-position-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 '{
  "vessels": [
    "IMO 9241061"
  ]
}' |
apify call nabeelbaghoor/vessel-tracking-ais-ship-position-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/vessel-tracking-ais-ship-position-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/6FMd3yBT56n7wvHM1/builds/PYKo9mXC5kGa0eucd/openapi.json