Vessel Tracking API

What is AIS Vessel Tracking?

The Automatic Identification System (AIS) is a tracking system used on ships and by vessel traffic services for identifying and locating vessels. AIS transceivers automatically broadcast information such as position, speed, and navigational status at regular intervals. The API collects this data from AIS transmissions and third-party maritime data providers, exposing it through REST endpoints.

With VesselAPI's vessel tracking endpoints, you can monitor fleet movements, track shipments, analyze maritime traffic patterns, and integrate live ship data into your applications. The API supports integration into logistics platforms, maritime analytics dashboards, and port management systems.

Use Cases

Vessel Identifiers

The API accepts two types of vessel identifiers. Understanding when to use each will help you build more robust integrations.

Automatic ID Resolution

When looking up a vessel by ID, the API automatically resolves the identifier if you use the wrong type. For example, if you pass an IMO number but set filter.idType=mmsi, the API will first attempt an MMSI lookup, and if no match is found, it will automatically try looking up the value as an IMO number (and vice versa).

This applies to all ID-based endpoints: /vessel/{id}, /vessel/{id}/position, /vessel/{id}/eta, and /vessels/positions.

Response Metadata

When a fallback resolution occurs, the response includes a _meta field indicating which ID type was actually used. This field is omitted when the primary lookup succeeds.

{
  "vessel": { ... },
  "_meta": {
    "requestedIdType": "mmsi",
    "resolvedIdType": "imo",
    "resolvedId": 9321483
  }
}

Satellite Position Fallback

Terrestrial AIS receivers cover coastal waters and port areas well, but lose signal on vessels in open ocean or other regions outside receiver range. For those cases, you can opt in to satellite AIS fallback by passing filter.sat=true on the position endpoint. Satellite lookups are billed separately from your subscription via one-time credit packs.

Where it's available

Satellite fallback is only supported on the last-known-position endpoint:

• GET /v1/vessel/{id}/position?filter.idType=mmsi&filter.sat=true

Other endpoints (ETA, port events, historical positions, fleet queries) are terrestrial-only and ignore the filter.sat parameter.

Update frequency

Satellite AIS is refreshed far less frequently than terrestrial. Where a vessel near a terrestrial receiver can broadcast a new position every few seconds, satellite positions typically update on the order of minutes to a few hours depending on satellite pass coverage and vessel location. If a recent terrestrial position is available for the vessel, the API will return that instead at no additional charge — satellite data is only used when terrestrial is not recent enough.

What you get charged for

One satellite credit is deducted per successful satellite position response. If the request is served from terrestrial data, or if no recent satellite position exists for the vessel, no credit is charged. You can inspect what was actually served using the response headers:

Coverage limits

Satellite AIS is not a guarantee of global coverage. Vessels in low-traffic regions, with AIS transponders switched off, or with obstructed sky view may have no recent satellite position at all. When that happens, the API returns 404 Not Found and no credit is charged. Satellite is a fallback mechanism, not a universal vessel locator.

Example request

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.vesselapi.com/v1/vessel/9321483/position?filter.idType=imo&filter.sat=true"

Buying credits

Satellite credits are sold in one-time packs of 50, 200, or 500 lookups. They are not part of your monthly subscription quota — they are a separate balance that does not renew and does not expire. Credits are available to any tier, including the Free tier. See the pricing page for pack details. Purchased satellite credits are non-refundable and not covered by the 14-day money-back guarantee on subscriptions.

Available Endpoints

Code Examples

Get Vessel Position (cURL)

curl -X GET "https://api.vesselapi.com/v1/vessel/253041000/position?filter.idType=mmsi" \
     -H "Authorization: Bearer YOUR_API_KEY"

Search Vessels by Name (Python)

import requests

response = requests.get(
    "https://api.vesselapi.com/v1/search/vessels",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"filter.name": "EVERGREEN", "pagination.limit": 20}
)

data = response.json()
for vessel in data["vessels"]:
    # Search results return Vessel objects with 'name' (not 'vessel_name')
    print(f"{vessel['name']} - MMSI: {vessel['mmsi']}")

Get Vessels in Area (JavaScript)

const response = await fetch(
  "https://api.vesselapi.com/v1/location/vessels/bounding-box?" +
  new URLSearchParams({
    "filter.latBottom": 51.0,
    "filter.latTop": 52.0,
    "filter.lonLeft": 3.0,
    "filter.lonRight": 4.5
  }),
  {
    headers: { "Authorization": "Bearer YOUR_API_KEY" }
  }
);

const data = await response.json();
console.log(`Found ${data.vessels.length} vessels in the area`);

Response Fields

Vessel Static Data (/vessel/{id}, /search/vessels)

Additional fields such as former_names, builder, class_society, home_port, engine_type, and kilowatt_power are also available. See the API Explorer for the complete schema.

Position Data (/vessel/{id}/position, /vessels/positions, /location/vessels/*)