Overview
The whole index is published as static JSON files over HTTPS. There is no key, no sign-up and no rate limit, and CORS is open, so you can call it straight from a browser.
Files are regenerated every time the index is updated. All endpoints are GET and live under:
https://liveaboardindex.com/api/v1
Quick start
Find a boat by IMO, then fetch its full record:
curl https://liveaboardindex.com/api/v1/lookup/imo/4902921.json
# {"id":"lvb_2f5255"}
curl https://liveaboardindex.com/api/v1/boats/lvb_2f5255.json
The same in JavaScript. A lookup that doesn't exist returns HTTP 404:
const base = 'https://liveaboardindex.com/api/v1'
const res = await fetch(`${base}/lookup/imo/4902921.json`)
if (res.status === 404) throw new Error('Not in the index')
const { id } = await res.json()
const boat = await fetch(`${base}/boats/${id}.json`).then((r) => r.json())
For search or filtering, download /boats.json once and filter it locally. It holds every active boat:
const boats = await fetch('https://liveaboardindex.com/api/v1/boats.json').then((r) => r.json())
const big = boats.filter((b) => b.guests >= 16 && b.region === 'antarctica')
Endpoints
| Path | Returns |
|---|---|
| /boats.json | Every active boat, compact |
| /boats/{id}.json | One boat, full record |
| /lookup/imo/{imo}.json | Boat ID by IMO |
| /lookup/mmsi/{mmsi}.json | Boat ID by MMSI |
| /regions.json | Every region |
| /regions/{id}.json | Boats in a region |
| /operators.json | Every active operator |
| /operators/{id}.json | One operator, full record |
List boats
/api/v1/boats.json
Every active boat in a compact form, sorted by name. Merged duplicates are left out.
Example: /api/v1/boats.json
[
{
"id": "lvb_jtp7yj",
"name": "Adelaar",
"url": "/boats/lvb_jtp7yj/adelaar",
"imo": null,
"mmsi": null,
"flag": null,
"region": "indonesia",
"operator": "op_j3cg",
"hull": null,
"loa_m": null,
"guests": 8,
"cabins": 4,
"status": "active"
},
{
"id": "lvb_n801bf",
"name": "Adora",
"url": "/boats/lvb_n801bf/adora",
"imo": null,
"mmsi": null,
"flag": null,
"region": "maldives",
"operator": "op_ze93",
"hull": null,
"loa_m": 38.1,
"guests": 21,
"cabins": 11,
"status": "active"
},
… 318 more
]
Get a boat
/api/v1/boats/{id}.json
The full record. Exists for every ID ever issued, including merged ones; see merges.
Example: /api/v1/boats/lvb_2f5255.json
{
"id": "lvb_2f5255",
"names": [
{
"name": "Aqua Blu",
"from": null,
"to": null
}
],
"hull": null,
"built": {
"year": 1968,
"yard": null
},
"imo": 4902921,
"mmsi": 525600798,
"call_sign": "YCWM2",
"flag": "ID",
"loa_m": 60,
"beam_m": 11.4,
"gt": 1140,
"refit_year": 2019,
"guests": 30,
"cabins": 15,
"bathrooms": 17,
"max_speed_kn": 15,
"cruising_speed_kn": 12,
"engines": {
"count": 4,
"make": null,
"model": null,
"power_hp": 660
},
"tenders": 5,
"fuel_l": 137000,
"water_l": null,
"watermaker_lpd": null,
"cabin_types": [
{
"name": "Category I Cabins (101, 104, 105)",
"count": null,
"max_guests": 2,
"beds": {
"single": 0,
"double": 1,
"bunk": 0,
"convertible": false
},
"size_m2": null,
"deck": "lower",
"window": "porthole",
"bathroom": "ensuite",
"aircon": true,
"external_ids": {
"liveaboard_com": 12203
}
},
{
"name": "Category I Cabins (202, 204)",
"count": null,
"max_guests": 2,
"beds": {
"single": 0,
"double": 1,
"bunk": 0,
"convertible": true
},
"size_m2": {
"min": 30,
"max": 34
},
"deck": "main",
"window": "standard",
"bathroom": "ensuite",
"aircon": true,
"external_ids": {
"liveaboard_com": 12204
}
},
{
"name": "Category I Cabins (302, 303, 402)",
"count": null,
"max_guests": 2,
"beds": {
"single": 0,
"double": 1,
"bunk": 0,
"convertible": false
},
"size_m2": null,
"deck": null,
"window": "standard",
"bathroom": "ensuite",
"aircon": true,
"external_ids": {
"liveaboard_com": 12205
}
},
{
"name": "Category II Cabin (201)",
"count": null,
"max_guests": 2,
"beds": {
"single": 0,
"double": 1,
"bunk": 0,
"convertible": false
},
"size_m2": {
"min": 24,
"max": 24
},
"deck": "main",
"window": "standard",
"bathroom": "ensuite",
"aircon": true,
"external_ids": {
"liveaboard_com": 12206
}
},
{
"name": "Category II Cabins (203, 301, 401)",
"count": null,
"max_guests": 2,
"beds": {
"single": 0,
"double": 1,
"bunk": 0,
"convertible": false
},
"size_m2": {
"min": 24,
"max": 24
},
"deck": null,
"window": "standard",
"bathroom": "ensuite",
"aircon": true,
"external_ids": {
"liveaboard_com": 12207
}
},
{
"name": "Category III Cabins (102, 103, 206)",
"count": null,
"max_guests": 2,
"beds": {
"single": 2,
"double": 0,
"bunk": 0,
"convertible": false
},
"size_m2": {
"min": 14,
"max": 14
},
"deck": null,
"window": "porthole",
"bathroom": "ensuite",
"aircon": true,
"external_ids": {
"liveaboard_com": 12208
}
}
],
"amenities": [
"ensuite_bathrooms",
"aircon_cabins",
"seaview_cabins",
"family_cabins",
"non_smoking_cabins",
"hot_showers",
"outside_showers",
"indoor_saloon",
"aircon_saloon",
"outdoor_dining",
"bar",
"sun_deck",
"observation_deck",
"leisure_deck",
"jacuzzi",
"massage",
"library",
"entertainment",
"internet",
"charging_stations",
"laundry",
"housekeeping",
"kayaks",
"paddleboards",
"snorkeling_gear",
"naturalist_guide",
"non_diver_friendly"
],
"dive_facilities": [
"gear_rental"
],
"safety": [
"radar",
"gps",
"vhf_dsc_ssb",
"satellite_phone",
"depth_sounder",
"searchlight",
"flares",
"life_rafts",
"life_vests",
"fire_suppression",
"oxygen",
"first_aid_kit",
"crew_first_aid"
],
"dining": [
"local_food",
"vegetarian",
"vegan",
"buffet",
"set_menu",
"snacks",
"beer",
"wine"
],
"languages": [
"en",
"id"
],
"operator": "op_9wwa",
"region": "indonesia",
"status": "active",
"merged_into": null,
"external_ids": {
"liveaboard_com": 6538
},
"sources": [
"https://www.liveaboard.com/diving/indonesia/aqua-blu",
"https://www.vesselfinder.com/vessels/details/4902921",
"https://www.vesselfinder.com/vessels/details/525600798"
],
"notes": "",
"name": "Aqua Blu",
"url": "/boats/lvb_2f5255/aqua-blu"
}
Look up by IMO or MMSI
/api/v1/lookup/imo/{imo}.json
/api/v1/lookup/mmsi/{mmsi}.json
Returns the ID of the active boat with that number, or HTTP 404 if there is none.
Examples: /api/v1/lookup/imo/4902921.json, /api/v1/lookup/mmsi/525600798.json
{
"id": "lvb_2f5255"
}
List regions
/api/v1/regions.json
Every region: { id, name, countries }, with ISO country codes.
Example: /api/v1/regions.json
[
{
"id": "antarctica",
"name": "Antarctica",
"countries": [
"AQ"
]
},
{
"id": "arctic",
"name": "Arctic",
"countries": [
"SJ",
"GL",
"NO"
]
},
… 27 more
]
Boats in a region
/api/v1/regions/{id}.json
Active boats in the region, in the same compact form as /boats.json. Only regions with at least one boat have a file.
Example: /api/v1/regions/antarctica.json
[
{
"id": "lvb_r23q0n",
"name": "Hondius Antarctica Diving",
"url": "/boats/lvb_r23q0n/hondius-antarctica-diving",
"imo": null,
"mmsi": null,
"flag": null,
"region": "antarctica",
"operator": "op_v0xg",
"hull": null,
"loa_m": 107.6,
"guests": 170,
"cabins": 80,
"status": "active"
},
{
"id": "lvb_wrv858",
"name": "Ortelius",
"url": "/boats/lvb_wrv858/ortelius",
"imo": null,
"mmsi": null,
"flag": null,
"region": "antarctica",
"operator": "op_v0xg",
"hull": null,
"loa_m": 90.95,
"guests": 108,
"cabins": 52,
"status": "active"
},
… 1 more
]
List operators
/api/v1/operators.json
Every active operator, with the number of active boats it runs.
Example: /api/v1/operators.json
[
{
"id": "op_062s",
"name": "A-One-Diving Company Limited",
"url": "/operators/op_062s/a-one-diving-company-limited",
"country": null,
"status": "active",
"boats": 1
},
{
"id": "op_j3cg",
"name": "Adelaar Cruises",
"url": "/operators/op_j3cg/adelaar-cruises",
"country": null,
"status": "active",
"boats": 1
},
… 191 more
]
Get an operator
/api/v1/operators/{id}.json
The full operator record.
Example: /api/v1/operators/op_9wwa.json
{
"id": "op_9wwa",
"names": [
{
"name": "Aqua Expeditions PTE. LTD.",
"from": null,
"to": null
}
],
"country": null,
"website": null,
"status": "active",
"merged_into": null,
"external_ids": {
"liveaboard_com": 1527
},
"sources": [],
"notes": "",
"name": "Aqua Expeditions PTE. LTD.",
"url": "/operators/op_9wwa/aqua-expeditions-pte-ltd"
}
IDs
Boats are lvb_ + 6 characters, operators op_ + 4, in lowercase Crockford base32 (no i, l, o or u). IDs are random, never change and are never reused, even if a boat is renamed, reflagged or sold.
Store the ID, not the name or IMO. IMO and MMSI are attributes: they can be missing, and an MMSI can change when a boat is reflagged.
API paths are exact and lowercase. Website URLs are forgiving: /boats/LVB_2F5255 and any slug redirect to the canonical page.
Merges
When two records turn out to be the same boat, one is kept and the other gets status: "merged" plus merged_into with the surviving ID. Merged records drop out of lists and lookups, but their /boats/{id}.json file stays forever, so stored IDs keep resolving. Follow merged_into to get the current record.
Boat fields
| Field | Type | Description |
|---|---|---|
| id | string | Permanent ID: lvb_ + 6 Crockford base32 characters. Never changes or gets reused. |
| name | string | Current name. |
| url | string | Canonical page on liveaboardindex.com. For merged boats, the page of the boat it was merged into. |
| names | array | Name history, oldest first: { name, from, to }. to: null marks the current name. Dates are a year, YYYY-MM or YYYY-MM-DD. |
| status | string | One of active, retired, lost, merged. |
| merged_into | string | null | When status is merged, the ID of the record this duplicate was merged into. |
| region | string | null | Region ID, see /regions.json. |
| operator | string | null | Operator ID (op_xxxx). |
| hull | string | null | <material>_<propulsion>. Materials: steel, wood, aluminium, fiberglass, composite. Propulsion: motor, sail, motor_sail. |
| built | object | { year, yard }, both nullable. |
| refit_year | number | null | Year of the last major refit. |
| guests | number | null | Maximum guests. |
| cabins | number | null | Guest cabins. |
| bathrooms | number | null | Number of bathrooms. |
| cabin_types | array | Cabin types: { name, count, max_guests, beds, size_m2, deck, window, bathroom, aircon, external_ids }. beds is { single, double, bunk, convertible }; size_m2 is { min, max }. Deck: lower, main, middle, upper, top, sun, across. Window: none, porthole, standard, picture, panoramic. Bathroom: ensuite, shared. count is the number of cabins of that type, when known. |
| amenities | string[] | On-board amenities: ensuite_bathrooms, aircon_cabins, seaview_cabins, family_cabins, non_smoking_cabins, tv_in_cabins, balcony_cabins, cabin_safe, hair_dryer, hot_showers, outside_showers, indoor_saloon, aircon_saloon, outdoor_dining, bar, bbq, sun_deck, observation_deck, leisure_deck, jacuzzi, pool, sauna, spa, massage, gym, shop, library, entertainment, internet, charging_stations, camera_station, camera_rinse, laundry, housekeeping, kayaks, paddleboards, fishing, water_ski, wakeboarding, jet_ski, glass_bottom_boat, snorkeling_gear, naturalist_guide, non_diver_friendly, purpose_built_dive, private_charter. |
| dive_facilities | string[] | Diving setup: dive_deck, shaded_dive_area, dive_tenders, rinse_hoses, nitrox, din_adaptors, sidemount, tech_diving, rebreathers, gear_rental. |
| safety | string[] | Navigation and safety equipment: radar, gps, vhf_dsc_ssb, satellite_phone, depth_sounder, fishfinder, searchlight, epirb, flares, life_rafts, life_vests, fire_suppression, bilge_alarm, engine_room_cctv, oxygen, first_aid_kit, crew_first_aid. |
| dining | string[] | Food and drink: local_food, western_food, vegetarian, vegan, buffet, set_menu, snacks, beach_bbq, beer, wine. |
| languages | string[] | Languages the crew speaks, ISO 639-1 (e.g. en, es). |
| max_speed_kn | number | null | Top speed, knots. |
| cruising_speed_kn | number | null | Cruising speed, knots. |
| engines | object | null | { count, make, model, power_hp }, power_hp per engine. Makes: caterpillar, cummins, detroit_diesel, deutz, john_deere, man, mitsubishi, mtu, mwm, perkins, scania, volvo_penta, yanmar. |
| tenders | number | null | Number of tenders (dinghies / skiffs). |
| fuel_l | number | null | Fuel capacity, liters. |
| water_l | number | null | Fresh water capacity, liters. |
| watermaker_lpd | number | null | Watermaker output, liters per day. |
| loa_m | number | null | Length overall, meters. |
| beam_m | number | null | Beam, meters. |
| gt | number | null | Gross tonnage. |
| imo | number | null | IMO number (7 digits, check digit validated). Unique across active boats. |
| mmsi | number | null | MMSI (9 digits). Unique across active boats. |
| call_sign | string | null | Radio call sign. |
| flag | string | null | Flag state, ISO 3166-1 alpha-2 (e.g. EC). |
| external_ids | object | IDs in other systems: { liveaboard_com }. |
| sources | string[] | URLs the data was checked against. |
| notes | string | Free-form editorial notes; empty string if none. |
Operator fields
| Field | Type | Description |
|---|---|---|
| id | string | Permanent ID: op_ + 4 Crockford base32 characters. |
| name | string | Current name. |
| url | string | Canonical page on liveaboardindex.com. |
| names | array | Name history, same shape as for boats. |
| status | string | One of active, defunct, merged. |
| merged_into | string | null | When merged, the ID of the operator it was merged into. |
| country | string | null | Home country, ISO 3166-1 alpha-2. |
| website | string | null | Official website. |
| external_ids | object | IDs in other systems: { liveaboard_com }. |
| sources | string[] | URLs the data was checked against. |
| notes | string | Free-form editorial notes; empty string if none. |
List endpoints return a subset of these fields. /operators.json adds boats, the number of active boats.
Versioning
Within v1, fields may be added but are never renamed, removed or changed in type, so ignore fields you don't know. A breaking change would ship as /api/v2 alongside v1.
Missing values are always null, never omitted.