Bunkerchain
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:
- A non-empty response does not mean the vessel was found. Only a blank
patternreturns[]. - Trust the ranking, not the presence of rows. The best match is first.
- To confirm an identity, verify the field you searched. If you searched a
call sign, check
callSignon the first result equals it. If you have an IMO, useGET /api/v1/vessels/{imo}instead — that is an exact lookup and 404s when there is no such vessel.
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
200with 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 from13.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
- No field-scoped search.
patternis one free-text term matched across all indexed fields; there is no syntax forflag:SGPorbuiltAfter=2010. To filter, fetch and filter client-side. - No boolean or wildcard operators.
*,AND,ORand quotes are treated as ordinary characters. - No delete. Records can be created and updated, never removed.
- No bulk endpoint.
PUTtakes one vessel per request. - No total count. A response is the page you asked for; there is no
totalfield. If a page returns fewer thansize, it is the last one.
Notes
- Search reads an Elasticsearch index kept in step with the database
automatically for writes made through this API — a
PUTis indexed in the same transaction, so it is searchable immediately and there is no cache to wait for. Changes made straight in the database bypass that and leave the index stale, which is a thing to know if anyone offers to "just fix it in SQL". sizeis capped at 200. For bulk extraction, page through withpage.- Rate limiting is not applied today. Be considerate, and tell us before starting a large backfill.