API reference

GET /v1/vessels/search

Search vessels by name, call sign, MMSI prefix or IMO.

Matches the vessel name or call sign (substring, case-insensitive), the start of an MMSI, or an exact IMO number. Results are ordered by when the vessel was last seen, newest first.

Response: query, offset, results (each with mmsi, name, imo, callsign, ship_type, length_m, last_seen) and next_offset (null on the last page). Search results carry no source field; the attribution is at /v1/sources.

Status codes: 200, 400, 401, 429, 503.

curl -H "Authorization: Bearer $AIS_TRAIL_KEY" \
  "https://api.aistrail.com/v1/vessels/search?q=MYSTAR"

GET /v1/vessels/{mmsi}

Vessel identity by MMSI: current static data and observation log.

Response: mmsi, current (latest known imo, name, callsign, ship_type, length_m, width_m, draught_m, destination, eta), first_seen, last_seen and observations: the distinct static reports the vessel has sent (up to 50, newest first), each with its first_seen, last_seen and sources. The response also has a live_position field; it is null on all current plans.

Passing a 7-digit IMO number here returns 400 with the IMO URL to use instead.

Status codes: 200, 400, 401, 404, 429, 503.

curl -H "Authorization: Bearer $AIS_TRAIL_KEY" \
  "https://api.aistrail.com/v1/vessels/276859000"

GET /v1/vessels/imo/{imo}

MMSIs that have reported this IMO number, newest first.

Ships change MMSI when they change flag. This lists every MMSI that has reported this IMO number, with the period (first_seen, last_seen), name and callsign; newest first, at most 50 (truncated is true beyond that). The IMO number must have a valid check digit.

Status codes: 200, 400, 401, 404, 429, 503.

curl -H "Authorization: Bearer $AIS_TRAIL_KEY" \
  "https://api.aistrail.com/v1/vessels/imo/9892690"

GET /v1/vessels/{mmsi}/track

Track of one MMSI over a time range.

Positions of one MMSI between from and to, ordered by time. Paged: see Paging. The default range is the 24 hours before to.

Status codes: 200, 400, 401, 403, 429, 503.

curl -H "Authorization: Bearer $AIS_TRAIL_KEY" \
  "https://api.aistrail.com/v1/vessels/276859000/track?from=2026-10-08T00:00:00Z&to=2026-10-09T00:00:00Z&resolution=1m"

On Free, use a day from the last 7 days: an older from returns 403 History limit.

Response, trimmed to the first position. embargo_cutoff is the time of your request minus 24 hours.

{
  "meta": {
    "mmsi": 276859000,
    "from": "2026-10-08T00:00:00Z",
    "to": "2026-10-09T00:00:00Z",
    "resolution": "1m",
    "count": 654,
    "complete": true,
    "next_cursor": null,
    "next": null,
    "embargo_cutoff": "2026-10-10T09:30:00Z",
    "attribution": [
      { "source": "<source id>",
        "text": "<attribution text of this source, see /v1/sources>",
        "license": "CC BY 4.0",
        "license_url": "https://creativecommons.org/licenses/by/4.0/" }
    ]
  },
  "positions": [
    { "mmsi": 276859000, "ts": "2026-10-08T00:17:23.383000Z",
      "lat": 60.14799, "lon": 24.91475, "sog": 0.0, "cog": 15.6,
      "heading": 207, "nav_status": 5, "source": "<source id>", "flags": null },
    …
  ]
}

Each source is a source id; the ids and their attribution are listed at /v1/sources.

GET /v1/vessels/imo/{imo}/track

Track of one ship by IMO number, across MMSI changes.

Follows one ship across MMSI changes. Each MMSI is included only for the periods in which it reported this IMO (±10 minutes), so positions of an unrelated ship that later reused the MMSI are not mixed in. Every row carries its mmsi. Same parameters and paging as the MMSI track.

Status codes: 200, 400, 401, 403, 429, 503.

curl -H "Authorization: Bearer $AIS_TRAIL_KEY" \
  "https://api.aistrail.com/v1/vessels/imo/9892690/track?from=2026-10-08&to=2026-10-09&resolution=1m"

GET /v1/area

Historical positions inside a bounding box (Pro and Business plans).

Every position inside a bounding box over a time range. Pro plan: each side up to 2°; Business plan: up to 10°. Free keys get 403 Plan limit. Boxes that cross the antimeridian are not supported. A box larger than your plan allows returns 400 Bad request. The default range is the hour before to.

Rows come day by day and, at raw resolution, 1° tile by tile; inside a tile they are ordered by vessel and time. Each page is time-boxed on the server, so a page can hold fewer rows than limit (even zero) while complete is still false: keep following next.

Area queries at 1m or 1h resolution, or with a side longer than 2°, run one at a time across the service: they wait in a queue instead of failing.

Status codes: 200, 400, 401, 403, 429, 503.

curl -H "Authorization: Bearer $AIS_TRAIL_KEY" \
  "https://api.aistrail.com/v1/area?bbox=54.95,10.6,55.6,11.25&from=2026-10-08T10:00:00Z&to=2026-10-08T12:00:00Z&resolution=1m"

GET /v1/usage

Plan, limits and usage in the current billing period.

Your plan and how much of it you have used: plan, label, limits, sources, requests_used (this billing period) and period_resets_at. The same numbers are in your dashboard. Each call counts as one request toward your quota.

Status codes: 200, 401, 429.

curl -H "Authorization: Bearer $AIS_TRAIL_KEY" "https://api.aistrail.com/v1/usage"

GET /v1/sources

Data sources, licenses, required attribution and coverage (public).

Public, no key needed. Each source with its id, name, license, license_url, homepage, required attribution text and live coverage (first_date, last_date, days, missing, positions, vessels), plus available_until (the embargo cutoff). See Data sources.

Status codes: 200.

curl "https://api.aistrail.com/v1/sources"

GET /v1/status

Service status and data coverage per source (public).

Public, no key needed. status, uptime_s, coverage per source, available_until and disk usage.

Status codes: 200.

curl "https://api.aistrail.com/v1/status"

GET /v1/openapi.json

This API as an OpenAPI 3.1 document (public).

Public. This API as an OpenAPI 3.1 document, for code generators and API clients. A copy is published at /docs/openapi.json.

Status codes: 200.

curl "https://api.aistrail.com/v1/openapi.json"