Vessel search and characteristics API

Two endpoints that answer "which ship is this?". Search finds a vessel from whatever identifier you happen to have; characteristics returns its full profile.

Almost everything else in Vessel & Voyage is keyed by IMO number, so this is usually where a workflow starts.

The two-step shape

Endpoint	Use it to
`GET /vessel-insights/v1/vessel-search`	Turn a partial name, an MMSI, a callsign or a set of filters into a list of candidate vessels
`GET /vessel-insights/v1/vessel-characteristics/{imo}`	Read one vessel's complete profile, keyed by IMO

Search returns enough to identify a vessel and pick the right one. Characteristics returns everything we hold about it.

Finding a vessel

Match on what you already have. Each identifier is matched exactly, except the name fragment.

You have	Search by	Rule that catches people out
An IMO number	`imo`	Exactly seven digits. We reject a wrong length instead of returning nothing
An AIS MMSI	`mmsi`	Exactly nine digits, same rejection behaviour
A radio callsign	`callsign`	Matched exactly, not as a fragment
Part of a name	`name_contains`	Trimmed first, then must be at least three characters
A Pole Star asset ID	`asset_id`	Must be a syntactically valid UUID

You can also search without an identifier at all, by narrowing on attributes. Every attribute filter comes as a matched pair, one to include and one to exclude:

vessel_status_incl / vessel_status_excl, see Vessel Statuses

flag_code_incl / flag_code_excl, ISO 3166-1 alpha-3 country codes

vessel_type_label_incl / vessel_type_label_excl, specific ship-type labels listed on Vessel Types

Results page with limit and offset, described on Pagination & Filtering.

Include and exclude combine, they do not cancel

Supplying multiple inclusion and exclusion filters works, as long as the two do not contradict each other. flag_code_incl=PAN&vessel_type_label_excl=Tug means Panamanian-flagged vessels that are not tugs. There is no precedence rule to learn: we apply exclusion to whatever inclusion left.

One thing to note: supplying both the inclusion and exclusion parameter for the same field will resul in an error.

Reading a vessel's profile

vessel-characteristics takes an IMO and returns one vessel. The response groups into five areas, several of them nested:

Group	Carries
Identity	IMO, MMSI, callsign, name, type, Pole Star asset ID
Physical	Dimensions, gross tonnage, deadweight, draught, displacement, hull type, speed
Ownership	Operator, registered owner, technical manager, ship manager, group beneficial owner
Registration	Flag with its effective date, port of registry, classification society, P&I club
Construction	Shipbuilder, build year, country of build

The nesting is the part worth knowing before you write a parser:

{
  "imo": "9169055",
  "name": "MSC ADRIANA II",
  "flag": {
    "name": "Liberia",
    "country_code": "LBR",
    "effective_date": "2017-11-12"
  },
  "dimensions": {
    "length": 216.0,
    "breadth": 26.7
  },
  "ownership": {
    "operator": "MSC",
    "registered_owner": "ADRIANA OCEANWAY LTD",
    "group_beneficial_owner": "MSC"
  }
}

flag.effective_date is the date the vessel took its current flag, not the date we recorded it. A recent effective date next to an older build year is a reflagging, which is usually what you were looking for.

From a name to a profile

Search on the fragment you have

Three characters minimum, after trimming.

Pick the right hull from the candidates

Names are not unique and are reused after a sale. Disambiguate on IMO, which is not.

Read the full profile by IMO

Cache on IMO, not on name or MMSI

An IMO number is assigned at build and stays with the hull for life. A name changes on sale, and an MMSI changes on reflagging. Both are attributes of a vessel, not identifiers for it. Key your own records on IMO and a reflagging shows up as a changed field instead of a new vessel.

Coverage

We hold current data for over 130,000 vessels in the global fleet, refreshed on an ongoing basis. Coverage is strongest for vessels with an IMO number. Smaller craft that carry an MMSI but no IMO are searchable, but will not resolve through vessel-characteristics, which is IMO-keyed by design.

Voyage Insights

What the vessel has been doing: port calls, zone events, AIS gaps and inspections.

Vessel Types

The type and class vocabulary the search filters expect.

Vessel Statuses

Every status label accepted by the status filters.

Overview

The two-step shape#

Finding a vessel#

Reading a vessel's profile#

From a name to a profile#

Coverage#

Related#

The two-step shape

Finding a vessel

Reading a vessel's profile

From a name to a profile

Coverage

Related