Ендпойнти

Проследяване на кораби

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.

Справочникът на ендпойнтите е на английски, както и самият API.

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.

Изисква обхвата ships scope.

Параметри

qstring · query stringзадължителен

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

Пример MSC OSCAR·Откъде идва стойността What your user typed.

limitinteger · query string

Default 20, maximum 100.

Пример 20·Откъде идва стойността 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.

Пример false·Откъде идва стойността 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

Примерен отговор

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"
}

Какво получавате

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.

Изисква обхвата ships scope.

Параметри

mmsistring · in the URL pathзадължителен

The vessel’s 9-digit MMSI.

Пример 355906000·Откъде идва стойността /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.

Пример false·Откъде идва стойността Your latency choice.

Example requests

Request

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

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

Примерен отговор

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"
}

Какво получавате

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.

Изисква обхвата ships scope.

Параметри

mmsistring · in the URL pathзадължителен

The vessel’s 9-digit MMSI.

Пример 355906000·Откъде идва стойността /api/vessels/search -> vessels[].mmsi

sincestring · query string

ISO 8601 date or datetime.

Пример 2026-10-01·Откъде идва стойността 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.

Пример 500·Откъде идва стойността 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

Примерен отговор

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.

Изисква обхвата ships scope.

Параметри

qstring · query string

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

Пример MSCU1234567·Откъде идва стойността Any number you registered.

statusenum · query string

Only shipments in this state.

Пример active·Откъде идва стойността active, arrived or cancelled.

limit / offsetinteger · query string

Page size and row offset.

Пример 50 / 0·Откъде идва стойността 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

Примерен отговор

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

Изисква обхвата ships scope.

Параметри

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.

Пример 355906000·Откъде идва стойността /api/vessels/search, or your booking paperwork.

referencestring · JSON body

Free text to search by later.

Пример PO-1189·Откъде идва стойността 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.

Пример MSCU1234567·Откъде идва стойността Your shipping documents.

carrierstring · JSON body

The shipping line.

Пример MSC·Откъде идва стойността Your shipping documents.

origin_port / destination_portstring · JSON body

Free-text ports.

Пример Antwerp / Varna·Откъде идва стойността 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).

Пример 2026-11-02·Откъде идва стойността Your shipping documents.

notesstring · JSON body

Free text.

Пример 2 cars, BMW 320d and Audi A4·Откъде идва стойността 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"}

Примерен отговор

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.

Изисква обхвата ships scope.

Параметри

shipment_idinteger · in the URL pathзадължителен

The shipment id.

Пример 42·Откъде идва стойността /api/shipments -> shipments[].id

track_limitinteger · query string

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

Пример 500·Откъде идва стойността How many points your map can draw.

Example request

Request

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

Примерен отговор

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.

Изисква обхвата ships scope.

Параметри

shipment_idinteger · in the URL pathзадължителен

The shipment id.

Пример 42·Откъде идва стойността /api/shipments -> shipments[].id

statusenum · JSON body

The new state.

Пример arrived·Откъде идва стойността 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.

Пример eta·Откъде идва стойността POST /api/shipments body fields.

Example request

Request

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

Примерен отговор

json

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

DELETE

/api/shipments/{shipment_id}

Stop following a shipment.

Изисква обхвата ships scope.

Параметри

shipment_idinteger · in the URL pathзадължителен

The shipment id.

Пример 42·Откъде идва стойността /api/shipments -> shipments[].id

Example request

Request

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

Примерен отговор

json

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