---
title: "Search vessels by name, call sign, MMSI prefix or IMO"
method: GET
path: "/v1/vessels/search"
---

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

`GET /v1/vessels/search`

## Request

- Base URL: `https://api.aistrail.com`
- URL: `https://api.aistrail.com/v1/vessels/search`
- Auth: HTTP bearer

## Query parameters

- `q` string, required
- `limit` integer
- `offset` integer

## Response `200`

Most recently seen first

- object
  - `query` string
  - `offset` integer
  - `results` VesselSummary[]
    - `mmsi` integer
    - `name` string, nullable
    - `imo` integer, nullable
    - `callsign` string, nullable
    - `ship_type` integer, nullable
    - `length_m` number, nullable
    - `last_seen` string, date-time
    - `sources` string[]
    - `flag` Flag, nullable: Flag derived from the MMSI's Maritime Identification Digits (ITU MID table). It is the flag of the ship station licence: usually, but not always, the registry flag. null when the MMSI is not a ship station (coast stations, SAR aircraft, AIS-SART/MOB/EPIRB, aids to navigation, handhelds) or its MID is not allocated.
      - `code` string: ISO 3166-1 alpha-2 country or territory code
      - `name` string: English short name
      - `source` 'mmsi'
    - `dwt_estimate` DwtEstimate, nullable: Estimated deadweight from AIS dimensions, not a registry value: tonnes = k x length x beam x draught, with k per hull (block coefficient, waterline length and lightship share folded into one factor) calibrated on vessels with published deadweight. null for implausible dimensions and for ship types where deadweight does not apply or the hull is unknown (tugs, pilot, search and rescue, port and law enforcement craft, military, sailing and pleasure craft, high speed craft, other and unknown types).
      - `tonnes` integer: Estimated deadweight, metric tonnes, rounded to 3 significant digits
      - `class` 'Handysize' | 'MR' | 'Panamax' | 'Aframax' | 'Suezmax' | 'VLCC' | 'ULCC' | 'Handymax' | 'Supramax' | 'Ultramax' | 'Post-Panamax' | 'Capesize' | 'VLOC' | 'Feeder' | 'New Panamax' | 'ULCV' | 'null', nullable: Industry size class: by estimated deadweight for tankers and bulk carriers, by dimensions for container ships; null for passenger and fishing vessels and below 10,000 t
      - `hull` 'tanker' | 'bulk' | 'container' | 'passenger' | 'fishing': Hull family used; for AIS cargo types bulk (dry bulk and general cargo) or container is inferred from the dimensions
      - `draught_m` number: Draught used, metres
      - `draught_source` 'ais_max' | 'typical': ais_max: the deepest draught the vessel has reported; typical: none reported, or too shallow to be a loaded draught, so a typical draught for the beam
      - `method` 'dimensions'
      - `note` string
    - `sanctions` string[]: Sanctions lists that name this row's IMO number (empty when none; CSV: joined with |). Informational, not a compliance determination: see Sanctions lists in the docs
  - `next_offset` integer, nullable
  - `meta` ResponseMeta
    - `embargo_cutoff` string, date-time, nullable: Data newer than this is not available on your plan (null on plans with live data)
    - `sources_through` object: Per source: the archive holds this source's data up to this time, never later than embargo_cutoff (null: no data yet)
    - `private_vessels` 'excluded' | 'included': Whether private vessels are part of this response for your account
    - `attribution` object[]: Required attribution for the sources in this response
    - `sanctions_lists` SanctionsLists: The sanctions lists checked for this response: per list its publication date, when AIS Trail fetched it and how many vessels it names (stale: the last fetch failed, the previous copy is used), plus a note
      - `lists` object
      - `note` string
    - `notice` string: Not-for-navigation notice (also in the X-Notice header)

## Other responses

- `400`: RFC 9457 problem details
- `401`: RFC 9457 problem details
- `402`: RFC 9457 problem details
- `429`: RFC 9457 problem details
- `503`: RFC 9457 problem details

---

[API](https://skmtc.dev/aistrail/apis/ais-trail-api.md) · [All operations](https://skmtc.dev/aistrail/apis/ais-trail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aistrail/apis/ais-trail-api/revisions/e829e4345208?raw)