BunkerchainBunkerchain

IHS Vessel API

Search and maintain IHS vessel records. Intended for other Bunkerchain systems; humans should use the console at https://ihs.bunkerchain.io/.

Base URL: https://ihs.bunkerchain.io/api/v1/vessels

This page is public and contains no credentials. API keys are issued on the admin-only API keys page of the console.

Recent changes

Both dated 2026-09-22, both capable of breaking an existing integration:

Change What to do
Five cadis* fields removed from every response (49 → 44 fields) Nothing, unless you read one. They described the upstream IHS record, not the vessel.
Unknown field names on PUT are now rejected with 400 instead of being silently discarded If your update was quietly doing nothing, this is why — the 400 names the fields and suggests the right ones.

The second one changed a silent failure into a loud one. If a PUT of yours starts returning 400 today, it was never fully working; the response tells you which names to use.

Authentication

Every request needs an X-API-Key header.

X-API-Key: <your key>
Response Meaning
401 the key is missing, wrong, or has been revoked
503 no keys are configured on the server at all

Keys are issued per consuming system, so one can be revoked without affecting the others. A key is shown once, when it is created — only a hash is stored.

Search vessels

GET /api/v1/vessels/search?pattern=<term>&size=<n>&page=<n>
Parameter Required Default Notes
pattern yes — vessel name, IMO number, call sign or MMSI. Blank returns []
size no 20 results per page, capped at 200
page no 0 zero-based

Matching is ranked: an exact IMO, call sign or MMSI outranks a name prefix, which outranks an interior name fragment, which outranks a company or ship-type match.

⚠️ Results are ranked, not filtered — read this before writing a client

Search is fuzzy. It matches three- and four-character fragments, so a query that corresponds to no real vessel still returns rows. Searching ZZZZNOSUCHVESSELZZZZ returns 20 results, because ZZ appears inside names like ZHEJIANG ZENGZHOU (ZZ075).

So:

Use search for "help a human pick a vessel", and GET /{imo} for "resolve this identifier".

curl -H "X-API-Key: $KEY" \
  "https://ihs.bunkerchain.io/api/v1/vessels/search?pattern=ASTRALIUM&size=20"

Returns a JSON array of vessel objects.

Fetch one vessel

GET /api/v1/vessels/{imo}

Returns a single vessel object, or 404 if the IMO is unknown.

curl -H "X-API-Key: $KEY" https://ihs.bunkerchain.io/api/v1/vessels/1000033

Create or update a vessel

PUT /api/v1/vessels
Content-Type: application/json

Keyed on imoNumber, which is required. Only the fields you send are applied — omitted fields keep their current values, so a partial body is a partial update. There is no way to blank a field through this endpoint.

curl -X PUT -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"imoNumber":"1000033","callSign":"MVWV7","flag":"GBI"}' \
  https://ihs.bunkerchain.io/api/v1/vessels

Returns the stored vessel, in the same shape as a search result. The change is indexed as part of the same transaction, so it is searchable immediately — no reindex is needed.

Writable fields — these 16, and only these:

vesselName, officialName, callSign, mmsi, flag, portOfRegistry, shipTypeDescription, companyName, managerName, groupOwnerName, grossTonnageGt, deadWeight, lengthOverall, beam, draught, dateOfBuild.

Plus imoNumber, which is the key rather than something you change — send it to say which vessel, not to rename one. (The writableFields list in a 400 includes it, so that list has 17 entries where this one has 16.)

A field name this API does not know is rejected, not ignored. Sending another system's vocabulary — shipName for vesselName, grossTonnage for grossTonnageGt — returns 400 naming the offending fields, and suggests the intended one where it can:

{
  "error": "unknown field(s): shipName, grossTonnage",
  "didYouMean": { "shipName": "vesselName", "grossTonnage": "grossTonnageGt" },
  "writableFields": ["imoNumber", "vesselName", "..."]
}

A real vessel field that simply is not writable (netTonnage, length, shipEmail, …) is accepted and reported rather than refused — the response is 200 with an ignoredFields array and a warning, so a partial write is never silent.

Changed 2026-09-22. This endpoint previously accepted anything and discarded what it could not map, returning 200 with the old values still in place. A caller updating a vessel with another system's field names saw success and lost most of the update.

JSON numbers are fine on the way in. "beam": 13.86 and "beam": "13.86" are equivalent; every field is stored and returned as a string, so the response will show "13.86" either way.

imoNumber is the only required field, on create and on update alike. There is no separate create endpoint: the same PUT creates when the IMO is new and updates when it is not. It is trimmed and upper-cased, but not validated — any non-blank string is accepted as an IMO.

Response shape

A vessel object has 44 fields.

If you are migrating from 13.214.194.152:8080, it is no longer identical. That instance returns 49 fields; this one returns the same 44 minus the five cadis* fields removed on 2026-09-22 (see below). Every field you were reading other than those is unchanged in name, type and nesting, so parsing needs no change unless you were reading a cadis* value — and if you were, it was metadata about the upstream record rather than about the vessel.

Every field is a JSON string except id, which is an integer. Fields with no value are null — they are never omitted, so the key set is identical on every record.

[
  {
    "id": 759639,
    "imoNumber": "1000033",
    "vesselName": "ASTRALIUM",
    "callSign": "MVWV7",
    "mmsi": "234028000",
    "flag": "GBI",
    "shipTypeDescription": "Yacht",
    "companyName": "Hill Robinson",
    "grossTonnageGt": "499",
    "lengthOverall": "45.5",
    "portOfRegistry": null
  }
]

The complete field list, in full:

id, imoNumber, vesselName, officialName, fishingVesselName, callSign, mmsi,
flag, portOfRegistry, shipTypeDescription, fishingVesselGearType,
companyName, companyCode, managerName, managerCode,
groupOwnerName, groupOwnerCode,
grossTonnageGt, netTonnage, deadWeight,
lengthOverall, length, beam, mouldedDepth, draught,
dateOfBuild, keelLayingDate, launchDate, completionDate,
shipBuilder, shipBuilderHullNumber, placeOfBuild, shipyardId,
subContractorHullPlace, subContractorHullNumber, hullMaterial,
email, shipEmail, telephone, website, linkedin, facebook,
lastUpdateDate, referenceId

Changed 2026-09-22. Five cadis* fields were removed — cadisSysRowStatus, cadisSystemTimestamp, cadisSystemInserted, cadisSystemUpdated, cadisSystemChangedBy. They were metadata about the upstream IHS record rather than about the vessel, and one of them carried the name of the IHS Markit employee who last edited the record. If you are migrating from 13.214.194.152:8080, note that instance still returns them.

⚠️ id is this system's internal row id, not a vessel identifier. It is not stable across a rebuild of the database. Key on imoNumber.

Errors

Every error returns JSON in the same shape, with no other keys:

{"error": "no vessel with IMO 9999999999"}
Status When Example error
400 imoNumber missing or blank on PUT imoNumber is required
401 missing, invalid or revoked API key Invalid or missing X-API-Key
404 unknown IMO on GET /{imo} no vessel with IMO 9999999999
405 wrong method for the path HTTP 405 Method Not Allowed
503 the server has no API keys configured API access is not configured

Search never 404s. It returns 200 with an array, which is [] only when pattern is blank — see the ranking note above. GET /{imo} is the only endpoint that reports "not found".

What this API does not do

Notes