JSON API
Everything behind this site is available as JSON, free and without a key. It is the same data the pages are rendered from, rebuilt every night from the primary lists.
https://sanctionedvessels.org/api/v1 — start there; it returns the endpoint list and the conventions below.
Endpoints
| Path | What it returns | Parameters |
|---|---|---|
/vessels | The directory. Every vessel with a page here, filtered and paged. | q, authority, status, flag, type, year_from, year_to, listed_year, dwt, sort, page, per_page (10–200, default 50) |
/vessels/{imo} | One vessel: names, flags, each authority’s listing with the document it came from, the event timeline and the companies named alongside it. | — |
/changes | Listing events, newest first. Each carries date_precision: exact when the authority published the date, inferred_from_diff when it was detected between two daily snapshots. | since, until (YYYY-MM-DD), authority, type (listed, delisted, amended), page, per_page |
/screen | Bulk screening. GET with a comma-separated list, or POST {"imos": [...]}. Up to 500 per request. | imos |
/gaps | Every published divergence set with its count, plus the full overlap matrix. | — |
/gaps/{key} | The vessels in one set. Keys are only-<authority>, <a>-not-<b>, or port-ban-only. | page, per_page |
/authorities | Who is covered, what kind of body they are, and how many vessels each lists. | — |
/sources | Every source, its licence, and when it was last fetched successfully. | — |
Try it
curl https://sanctionedvessels.org/api/v1/vessels/9179842
curl "https://sanctionedvessels.org/api/v1/changes?since=2026-08-01&type=listed"
curl -X POST https://sanctionedvessels.org/api/v1/screen \
-H 'content-type: application/json' \
-d '{"imos": ["9179842", "9233739"]}'Conventions
- Freshness. Every response carries a
metablock withdata_refreshed_at, so you always know how old the answer is. The pipeline runs nightly. - Stability. Fields are only ever added within
v1. Anything that would break a client would be published as a new version, and this one would keep working. - Errors. Non-2xx responses are
{"error": {"code": "...", "message": "..."}}. Codes are stable; messages may be reworded. - Rate limit. 300 requests an hour per address, answered with 429 and a
Retry-Afterheader. If you need the whole dataset, take the CSV in one request instead of paging through it. - Caching. Responses are cacheable for 30 minutes, which is well inside the nightly refresh.
- CORS. Allowed from any origin, so it works from a browser.
- Identifiers. The IMO number is the only join key. A seven-digit number that fails the IMO check digit is rejected rather than looked up: it is usually an IMO company number, which identifies an owner or manager and never a hull.
Licence and attribution
This compilation is licensed CC BY 4.0. Attribute it to Sanctioned Vessels with a link to sanctionedvessels.org. The underlying lists carry their own terms — the UK list is Open Government Licence v3.0, the Australian list CC BY 3.0 AU, and so on; /sources gives the licence for each.
This API reports what published lists say, with a link to each primary document. It is not a screening tool of record: it holds no UN or Japanese designations, it cannot see an entity listed under a name with no IMO number attached, and an absence of a record is not a compliance clearance. Check the primary source before acting on anything here.
Something missing, or a shape that would be easier to consume? Say so — the API is meant to be used.