Endpoints

Ship tracking

Find any vessel and follow its position, voyage and route, and register your own shipments by tracking, B/L or container number so their vessel is followed for you. Scope: ships, granted per contract — not on a new key by default. Shipments are scoped to the key that registered them.

Following a shipment

1Register it with POST /api/shipments, giving the vessel as mmsi, imo or vessel_name plus whichever of your own numbers you want to search by later. A name is resolved to an MMSI; vessel_resolved says whether that worked.
2Read GET /api/shipments/{shipment_id} for the shipment, its vessel exactly as /api/vessels/{mmsi} returns it, and the route since you registered it.
3Mark it arrived with PATCH (status: arrived) or stop following it with DELETE. Either way it stays readable.

GET

/api/vessels/search

Find vessels by name, MMSI, IMO or call sign.

Requires the ships scope.

Parameters

qstring · query stringrequired

Exact MMSI (9 digits), IMO (7 digits, IMO prefix optional), call sign, or any part of the name. At least 3 characters.

Example MSC OSCAR·Where the value comes from What your user typed.

limitinteger · query string

Default 20, maximum 100.

Example 20·Where the value comes from How many results you show.

onlineboolean · query string

Default true: when nothing is known and q is a name, the exact name is looked up on a public vessel directory and remembered (source: vesselfinder). false answers from what we already know.

Example false·Where the value comes from Your latency choice.

Example requests

Request

GET https://api.thecarapi.com/api/vessels/search?q=MSC%20OSCAR

GET https://api.thecarapi.com/api/vessels/search?q=9703291

Example response

json

{
  "success": true,
  "source": "known",
  "vessels": [
    {
      "mmsi": "355906000",
      "imo": "9703291",
      "name": "MSC OSCAR",
      "call_sign": "3FOB4",
      "ship_type": "cargo",
      "length_m": 395,
      "width_m": 59,
      "destination": "ROTTERDAM",
      "last_position": {
        "latitude": 51.95,
        "longitude": 4.05,
        "speed_knots": 0.1,
        "time": "2026-10-18T09:12:00Z"
      }
    }
  ],
  "contract_version": "2026-10-05"
}

What you get back

sourceenum | null

known (from our AIS feed and earlier look-ups) or vesselfinder (found by the online look-up just now). null when nothing matched.

vessels[]object[]

mmsi, imo, name, call_sign, ship_type, length_m, width_m, destination and last_position { latitude, longitude, speed_knots, time } or null.

GET

/api/vessels/{mmsi}

Everything known about one vessel: identity, declared voyage, latest position and how much track we hold.

Requires the ships scope.

Parameters

mmsistring · in the URL pathrequired

The vessel’s 9-digit MMSI.

Example 355906000·Where the value comes from /api/vessels/search -> vessels[].mmsi

refreshboolean · query string

Default true: when our latest fix is older than 30 minutes it is refreshed from a public AIS source during the request. false answers from what is stored.

Example false·Where the value comes from Your latency choice.

Example requests

Request

GET https://api.thecarapi.com/api/vessels/355906000

GET https://api.thecarapi.com/api/vessels/355906000?refresh=false

Example response

json

{
  "success": true,
  "vessel": {
    "mmsi": "355906000",
    "imo": "9703291",
    "name": "MSC OSCAR",
    "call_sign": "3FOB4",
    "ship_type": "cargo",
    "length_m": 395,
    "width_m": 59,
    "max_draught_m": 16,
    "declared_destination": "ROTTERDAM",
    "declared_eta": "2026-10-19T06:00:00Z",
    "position": {
      "latitude": 51.95,
      "longitude": 4.05,
      "speed_knots": 0.1,
      "course": 182,
      "heading": 180,
      "nav_status": "moored",
      "area": "North Sea",
      "time": "2026-10-18T09:12:00Z",
      "source": "AISStream"
    },
    "voyage": {
      "departure_port": "Algeciras",
      "departed_at": "2026-10-14T21:30:00Z",
      "progress_pct": 96
    },
    "track": {
      "points": 1840,
      "first": "2026-08-01T00:04:00Z",
      "last": "2026-10-18T09:12:00Z"
    },
    "tracked_live": true
  },
  "contract_version": "2026-10-05"
}

What you get back

positionobject | null

Latest fix: latitude, longitude, speed_knots, course, heading, nav_status, area, time and source.

voyageobject

departure_port, departed_at and progress_pct where known.

trackobject

How many track points we hold and the first and last of them. Read them with /api/vessels/{mmsi}/track.

tracked_liveboolean

Whether the vessel is in the live AIS subscription right now.

GET

/api/vessels/{mmsi}/track

The vessel’s recorded route, oldest first.

Requires the ships scope.

Parameters

mmsistring · in the URL pathrequired

The vessel’s 9-digit MMSI.

Example 355906000·Where the value comes from /api/vessels/search -> vessels[].mmsi

sincestring · query string

ISO 8601 date or datetime.

Example 2026-10-01·Where the value comes from The start of the window you draw.

limitinteger · query string

The track is thinned evenly to at most this many points. Default 500, maximum 5000.

Example 500·Where the value comes from How many points your map can draw.

Example request

Request

GET https://api.thecarapi.com/api/vessels/355906000/track?since=2026-10-01&limit=500

Example response

json

{
  "success": true,
  "mmsi": "355906000",
  "track": [
    {
      "latitude": 36.1,
      "longitude": -5.4,
      "speed_knots": 14.2,
      "course": 12,
      "time": "2026-10-14T22:00:00Z"
    }
  ],
  "contract_version": "2026-10-05"
}

GET

/api/shipments

The calling key’s shipments, newest first.

Requires the ships scope.

Parameters

qstring · query string

Matches the reference, tracking / B/L / container / booking number, vessel name, MMSI or IMO, ignoring case and punctuation.

Example MSCU1234567·Where the value comes from Any number you registered.

statusenum · query string

Only shipments in this state.

Example active·Where the value comes from active, arrived or cancelled.

limit / offsetinteger · query string

Page size and row offset.

Example 50 / 0·Where the value comes from Pagination state in your application.

Example requests

Request

GET https://api.thecarapi.com/api/shipments?status=active

GET https://api.thecarapi.com/api/shipments?q=MSCU1234567

Example response

json

{
  "success": true,
  "shipments": [
    {
      "id": 42,
      "reference": "PO-1189",
      "container_number": "MSCU1234567",
      "vessel_name": "MSC OSCAR",
      "mmsi": "355906000",
      "imo": "9703291",
      "destination_port": "Varna",
      "eta": "2026-11-02",
      "status": "active",
      "vessel_resolved": true,
      "created_at": "2026-10-12T08:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "contract_version": "2026-10-05"
}

POST

/api/shipments

Requires the ships scope.

Parameters

mmsi / imo / vessel_namestring · JSON body

The vessel, given any one way. A name or IMO is resolved to an MMSI; vessel_resolved in the response says whether that worked.

Example 355906000·Where the value comes from /api/vessels/search, or your booking paperwork.

referencestring · JSON body

Free text to search by later.

Example PO-1189·Where the value comes from Your own reference.

tracking_number / bl_number / container_number / booking_numberstring · JSON body

Numbers to search by later. Container numbers are upper-cased and stripped of punctuation.

Example MSCU1234567·Where the value comes from Your shipping documents.

carrierstring · JSON body

The shipping line.

Example MSC·Where the value comes from Your shipping documents.

origin_port / destination_portstring · JSON body

Free-text ports.

Example Antwerp / Varna·Where the value comes from Your shipping documents.

etastring · JSON body

Expected arrival, ISO date. The vessel is followed until 14 days after it (90 days after creation without one).

Example 2026-11-02·Where the value comes from Your shipping documents.

notesstring · JSON body

Free text.

Example 2 cars, BMW 320d and Audi A4·Where the value comes from Anything you want to keep with it.

Example request

Request

POST https://api.thecarapi.com/api/shipments
{"reference": "PO-1189", "container_number": "MSCU1234567", "vessel_name": "MSC OSCAR", "destination_port": "Varna", "eta": "2026-11-02"}

Example response

json

{
  "success": true,
  "shipment": {
    "id": 42,
    "reference": "PO-1189",
    "container_number": "MSCU1234567",
    "vessel_name": "MSC OSCAR",
    "mmsi": "355906000",
    "status": "active",
    "vessel_resolved": true
  },
  "contract_version": "2026-10-05"
}

GET

/api/shipments/{shipment_id}

One shipment with its vessel and its route since registration.

Requires the ships scope.

Parameters

shipment_idinteger · in the URL pathrequired

The shipment id.

Example 42·Where the value comes from /api/shipments -> shipments[].id

track_limitinteger · query string

Track points, thinned evenly. Default 500, maximum 5000.

Example 500·Where the value comes from How many points your map can draw.

Example request

Request

GET https://api.thecarapi.com/api/shipments/42

Example response

json

{
  "success": true,
  "shipment": {
    "id": 42,
    "reference": "PO-1189",
    "status": "active",
    "mmsi": "355906000",
    "vessel": {
      "mmsi": "355906000",
      "name": "MSC OSCAR",
      "position": {
        "latitude": 51.95,
        "longitude": 4.05
      }
    },
    "track": []
  },
  "contract_version": "2026-10-05"
}

PATCH

/api/shipments/{shipment_id}

Change a shipment.

Requires the ships scope.

Parameters

shipment_idinteger · in the URL pathrequired

The shipment id.

Example 42·Where the value comes from /api/shipments -> shipments[].id

statusenum · JSON body

The new state.

Example arrived·Where the value comes from active, arrived or cancelled.

any create fieldstring · JSON body

Any field from the create body. A new vessel name or IMO re-resolves the MMSI.

Example eta·Where the value comes from POST /api/shipments body fields.

Example request

Request

PATCH https://api.thecarapi.com/api/shipments/42
{"status": "arrived"}

Example response

json

{
  "success": true,
  "shipment": {
    "id": 42,
    "status": "arrived"
  },
  "contract_version": "2026-10-05"
}

DELETE

/api/shipments/{shipment_id}

Stop following a shipment.

Requires the ships scope.

Parameters

shipment_idinteger · in the URL pathrequired

The shipment id.

Example 42·Where the value comes from /api/shipments -> shipments[].id

Example request

Request

DELETE https://api.thecarapi.com/api/shipments/42

Example response

json

{
  "success": true,
  "shipment": {
    "id": 42,
    "status": "cancelled"
  },
  "contract_version": "2026-10-05"
}