# 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
  `pattern` returns `[]`.
- **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 `callSign` on the first result equals it. If you have an IMO,
  use `GET /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".

```bash
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.

```bash
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.

```bash
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:

```json
{
  "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.

```json
[
  {
    "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:

```json
{"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.** `pattern` is one free-text term matched across all
  indexed fields; there is no syntax for `flag:SGP` or `builtAfter=2010`. To
  filter, fetch and filter client-side.
- **No boolean or wildcard operators.** `*`, `AND`, `OR` and quotes are treated
  as ordinary characters.
- **No delete.** Records can be created and updated, never removed.
- **No bulk endpoint.** `PUT` takes one vessel per request.
- **No total count.** A response is the page you asked for; there is no
  `total` field. If a page returns fewer than `size`, 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 `PUT` is 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".
- `size` is capped at 200. For bulk extraction, page through with `page`.
- Rate limiting is not applied today. Be considerate, and tell us before
  starting a large backfill.
