# Vessel Class Finder

> JSON REST API for IACS vessel classification data. Look up any ship by IMO number and get its classification society, class status (Delivered / Reinstated / Reassigned / Suspended / Withdrawn), last and next survey dates, and the reason for its latest status change. Data comes from the IACS "Vessels in Class" dataset, which IACS publishes only as a ZIP/CSV download, and is refreshed every Sunday. Free tier: 100 lookups/month. Built by WeAreFabbrik (https://wearefabbrik.com).

Base URL: https://vessel-class-finder-production.up.railway.app
Authentication: `x-api-key` header. Get a key by registering, verifying your email, then logging in.

## Quick start

1. `POST /register` with `{"email": "...", "password": "..."}` (password min. 6 characters). A verification link is emailed to you.
2. Click the link (`GET /verify?token=...`). Unverified accounts cannot log in. `POST /resend-verification` with `{"email": "..."}` sends a new link.
3. `POST /login` with the same credentials. Returns `{"token": "...", "apiKey": "..."}`. Logging in again returns the same active key.
4. `POST /vessels` with header `x-api-key: <apiKey>` and body `{"imos": [9811000, 9321483]}`.

Example response from `/vessels`:

```json
[{
  "imo": 9811000,
  "vessel_name": "EVER GIVEN",
  "update_date": "01/03/26",
  "class": "ABS",
  "status": "Delivered",
  "date_of_survey": "12/07/2023",
  "date_of_next_survey": "24/09/2028",
  "date_of_latest_status": "25/10/2018",
  "reason_for_status": ""
}]
```

Dates are DD/MM/YYYY strings. IMO numbers not found in the IACS dataset are omitted from the response rather than returned as errors.

## Endpoints

- `POST /register`: create an account (sends a verification email)
- `GET /verify?token=...`: verify an email address
- `POST /resend-verification`: resend the verification email
- `POST /login`: returns a JWT and a new API key
- `POST /vessels` (API key): classification records for up to 100 IMO numbers per request. Each unique IMO counts as one lookup; invalid input is rejected with 400 and not charged.
- `GET /usage` (API key): `{"month", "used", "limit", "plan"}` for the current calendar month
- `GET /subscription` (API key): subscription status and expiry
- `GET /api-keys` (API key): list your API keys
- `DELETE /api-keys/:key` (API key): revoke a key
- `POST /billing/checkout` (API key): `{"plan": "starter" | "pro"}` returns `{"url"}` for a Stripe Checkout page
- `POST /billing/portal` (API key): returns `{"url"}` for the Stripe billing portal (change plan, update card, cancel, invoices)
- `GET /demo/:imo`: no key needed, one vessel per request, 10 requests/hour per IP, for trying the data

Errors are JSON `{"error": "..."}`. Status codes: 400 invalid input (non-numeric IMOs, empty list, more than 100 IMOs), 401 bad credentials, 403 missing/invalid API key or unverified email, 404 not found, 429 monthly quota or rate limit exceeded.

## Plans

- Free: 100 lookups/month, €0
- Starter: 5,000 lookups/month, €49/mo
- Pro: 50,000 lookups/month, €199/mo
- Enterprise: unlimited, custom pricing

Upgrade by card at https://vesselclassfinder.com/#pricing (log in, choose a plan, pay through Stripe; the new limit applies within a minute). A 429 response includes an `upgrade_url`. For Enterprise, email info@wearefabbrik.com.

## Data coverage

Every vessel in the IACS Vessels in Class dataset, which covers ships classed by IACS member societies: ABS, BV, CCS, CRS, DNV, IRS, KR, LR, ClassNK, PRS, RINA, TL. Typical uses include fleet monitoring, marine insurance risk checks, port state compliance, sale-and-purchase due diligence, and enriching vessel records.

## Links

- [Home page](https://vesselclassfinder.com/): overview, pricing, signup
- [Guide: querying IACS class status by IMO number](https://vesselclassfinder.com/blog/vessel-classification-api.html)
- [MCP server for Claude and AI assistants](https://vesselclassfinder.com/mcp.html): remote MCP endpoint https://vessel-class-finder-production.up.railway.app/mcp with tools lookup_vessel (no key needed), lookup_vessels and check_usage (API key as Bearer token)
- [IACS class status codes explained](https://vesselclassfinder.com/iacs-class-status-codes.html): what Delivered, Reinstated, Reassigned, Suspended and Withdrawn mean, plus every reason code, with current counts
- [IACS classification societies compared](https://vesselclassfinder.com/class-societies/): codes (NV = DNV, NKK = ClassNK, LRS = Lloyd's Register, TLV = Türk Loydu), fleet sizes and status breakdowns
- [ClassNK class status lookup](https://vesselclassfinder.com/class-societies/classnk.html): IACS code NKK
- [Bureau Veritas class status lookup](https://vesselclassfinder.com/class-societies/bureau-veritas.html): IACS code BV
- [ABS class status lookup](https://vesselclassfinder.com/class-societies/abs.html): IACS code ABS
- [DNV class status lookup](https://vesselclassfinder.com/class-societies/dnv.html): IACS code NV
- [Lloyd's Register class status lookup](https://vesselclassfinder.com/class-societies/lloyds-register.html): IACS code LRS
- [RINA class status lookup](https://vesselclassfinder.com/class-societies/rina.html): IACS code RINA
- [China Classification Society class status lookup](https://vesselclassfinder.com/class-societies/china-classification-society.html): IACS code CCS
- [Korean Register class status lookup](https://vesselclassfinder.com/class-societies/korean-register.html): IACS code KR
- [Indian Register of Shipping class status lookup](https://vesselclassfinder.com/class-societies/indian-register.html): IACS code IRS
- [Polish Register of Shipping class status lookup](https://vesselclassfinder.com/class-societies/polish-register.html): IACS code PRS
- [Croatian Register of Shipping class status lookup](https://vesselclassfinder.com/class-societies/croatian-register.html): IACS code CRS
- [Türk Loydu class status lookup](https://vesselclassfinder.com/class-societies/turk-loydu.html): IACS code TLV
- [Vessel class checks for sanctions and KYC screening](https://vesselclassfinder.com/use-cases/sanctions-kyc-screening.html)
- [Class status checks for charter vetting](https://vesselclassfinder.com/use-cases/charter-vetting.html)
- [Class status for marine insurance underwriting](https://vesselclassfinder.com/use-cases/marine-insurance.html)
- [Source code and full API reference](https://github.com/tsolman/vessel-class-finder)
- [Terms of Service & Privacy Policy](https://vesselclassfinder.com/terms.html)

## Guides

- [All articles](https://vesselclassfinder.com/blog/)
- [Why does marine insurance depend on a ship keeping its class?](https://vesselclassfinder.com/blog/class-and-marine-insurance.html): How class status ties into hull and machinery and P&I cover, what suspension or withdrawal can mean for a policy, and how to monitor a book of vessels.
- [What is the difference between class suspended and class withdrawn?](https://vesselclassfinder.com/blog/class-suspended-vs-withdrawn.html): Suspended class is temporary and can be reinstated. Withdrawn means the society no longer classes the ship. Causes, consequences and the numbers.
- [How to check a ship's class status by IMO number](https://vesselclassfinder.com/blog/how-to-check-vessel-class-status.html): Find the IMO number, look it up in the IACS Vessels in Class data, and read status, survey dates and reason fields correctly.
- [What does it mean if a ship is classed by a non-IACS society?](https://vesselclassfinder.com/blog/non-iacs-classification-societies.html): Ships classed outside IACS: why it raises due-diligence questions, how 431 ships moved to non-IACS class, and what the IACS data can and cannot show.
- [What class red flags are associated with the shadow fleet?](https://vesselclassfinder.com/blog/shadow-fleet-class-red-flags.html): Class withdrawals, overdue surveys and moves to non-IACS societies: which class signals matter in shadow fleet screening, and what they cannot prove.
- [How does the ship survey cycle work?](https://vesselclassfinder.com/blog/ship-survey-cycle-explained.html): Annual, intermediate and special surveys, bottom surveys in dry dock, and how to read survey dates and Survey overdue in IACS class data.
- [What is a transfer of class and why do ships change classification society?](https://vesselclassfinder.com/blog/transfer-of-class.html): Ships move between classification societies for ordinary commercial reasons, and sometimes to dodge scrutiny. How transfers work and what to check.
- [What is a classification society?](https://vesselclassfinder.com/blog/what-is-a-classification-society.html): What ship classification societies do, how class differs from statutory certification, and why insurers, charterers, flags and lenders require it.
- [What is an IMO number?](https://vesselclassfinder.com/blog/what-is-an-imo-number.html): The seven-digit IMO number identifies a ship for life. How the check digit works, who issues it, and why it beats name or MMSI for lookups.
- [What is IACS?](https://vesselclassfinder.com/blog/what-is-iacs.html): IACS explained: the 12 member class societies and their ship counts, Unified Requirements and CSR, and what the Vessels in Class dataset can tell you.