List Boats

GET/boats

Retrieve a paginated list of boats with optional filters for search, type, capacity, price, and more. Only active, published boats are returned.

Authentication

No authentication required for server-side requests — this is a public read endpoint. (A key is only needed for cross-origin calls made from a browser on another domain; see Authentication.)

Query Parameters

Pagination

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (max 50)
`offset`	integer	0	Number of results to skip

Search

Parameter	Type	Description
`q`	string	Free-text filter on boat title and model.
`d`	string	Availability date filter. Single date `YYYY-MM-DD` or range `YYYY-MM-DD,YYYY-MM-DD`. Ranges over 14 days match weeks where the boat has any availability.

Location Filters

Parameter	Type	Description
`location_id`	integer	Filter by exact location ID
`location_type`	string	One of `country`, `state`, `city`, `municipality`, `text`. Used with `location_value`.
`location_value`	string	The value to match for the given `location_type`

| country_code | string | Narrow state/city location searches by country code (e.g. HR, GR) |

With location_type=text the value is resolved as a free-text place name, which also accepts named sailing regions (Dalmatia, the Dodecanese). The other types look the value up directly and fall back to that same resolver when the direct lookup finds nothing, so a place is only reported unknown once both have failed.

Whatever the type, a value that resolves to no known place returns location_unresolved with an empty boats array and total: 0. The location is never silently dropped, so a response is never a worldwide search wearing the label of a place.

Boat Filters

Parameter	Type	Description
`type`	string	Boat type. Comma-separated for multiple: `yacht`, `catamaran`, `sailboat`, `motorboat`, `rib`, `other`
`guests`	integer	Minimum guest capacity
`cabins`	integer	Minimum number of cabins
`berths`	integer	Minimum number of berths
`toilets`	integer	Minimum number of toilets
`priceMin`	number	Minimum daily price
`priceMax`	number	Maximum daily price
`lengthMin`	number	Minimum length in feet
`lengthMax`	number	Maximum length in feet
`yearMin`	integer	Minimum build year (values 2000 or under are ignored)
`yearMax`	integer	Maximum build year
`rating`	number	Minimum average rating
`rentalTypes`	string	Comma-separated: `bareboat`, `skippered`, `cabin`, `flotilla`
`manufacturerSlug`	string	Filter by manufacturer slug
`features`	string	Comma-separated equipment/amenity terms, AND semantics. Accepts canonical slugs (`watermaker`), namespaced attribute tags (`dinghy:hypalon`), and loose synonyms (`ac` resolves to `air_conditioning`). The canonical vocabulary is served by `GET /api/features`.

Parameter	Type	Description
`facet_counts`	`1`	Adds a `facets` object to the response: per-feature boat counts (concept slugs and attribute tags) aggregated over the full matched result set — contextual to every filter in the request, never global. Features no boat in the set carries are omitted. Combine with `limit=0` for a cheap counts-only request (`boats` comes back empty).

# How many catamarans in the current search carry each feature?
curl "https://charter.boats/api/boats?type=catamaran&facet_counts=1&limit=0"

{
  "boats": [],
  "total": 3995,
  "facets": { "sound_system": 3416, "dinghy": 2905, "dinghy:hard_bottom": 312, "tv:smart": 63 }
}

Sorting

Parameter	Type	Default	Description
`sort` or `sortBy`	string	`recommended`	Sort order: `recommended`, `price-low`, `price-high`, `rating` (aliases `price_asc`/`price_desc` accepted)

Company Filters

Parameter	Type	Description
`company_slug`	string	Show only boats from this company
`priority_company`	string	Company slug whose boats are floated to the top of the results
`ids`	string	Comma-separated boat IDs to fetch specific boats

Request

# List all boats (first page)
curl https://charter.boats/api/boats
 
# Filter by type and capacity
curl "https://charter.boats/api/boats?type=catamaran&guests=6"
 
# Price range with sorting, page 2
curl "https://charter.boats/api/boats?priceMin=100&priceMax=500&sort=price-low&limit=20&offset=20"
 
# Filter by country
curl "https://charter.boats/api/boats?location_type=country&location_value=GR"

Response

{
  "boats": [
    {
      "id": "a4160684-f461-4192-ba70-2a6c929838ff",
      "slug": "fountaine-pajot-galapagos-tribute-fountaine-pajot-galapagos-tribute-138ft-catama",
      "title": "Galapagos Tribute - Premium Suite",
      "boat_type": "yacht",
      "capacity": 2,
      "length_ft": 138,
      "year": 2008,
      "price_per_day": 1500,
      "price_from": null,
      "price_to": null,
      "discount_percentage": null,
      "discount_label": null,
      "original_price_per_day": null,
      "average_rating": null,
      "review_count": 0,
      "location_id": 23248,
      "manufacturer_id": "8425d598-5ce9-40c2-ab30-6018cfe797d9",
      "company_id": "da9d3731-d87f-4289-98eb-7a24cb937288",
      "avail_weeks": 0,
      "hero_image_url": "https://pub-1d6bb2ea901f4e66a126571a99715069.r2.dev/boats/a4160684-f461-4192-ba70-2a6c929838ff/images/1780435184583_0.jpg",
      "has_valid_name": null,
      "model": "Galapagos Tribute",
      "manufacturer": {
        "id": "8425d598-5ce9-40c2-ab30-6018cfe797d9",
        "name": "Fountaine Pajot",
        "slug": "fountaine-pajot",
        "logo_url": null
      },
      "location": {
        "id": 23248,
        "city": "Parroquia Puerto Baquerizo Moreno",
        "name": "San Cristobal",
        "country": "Ecuador"
      },
      "amenities": [],
      "skippered": true,
      "currency": "EUR",
      "internal_discount_pct": null,
      "required_extras": null
    }
  ],
  "total": 12721,
  "limit": 20,
  "offset": 0,
  "next_offset": 20,
  "hasMore": true,
  "backfill_start_index": null
}

Response Fields

Field	Type	Description
`boats`	array	Array of boat objects
`total`	integer	Total number of matching boats
`limit`	integer	Page size used
`offset`	integer	Offset used
`next_offset`	integer	Offset to pass for the next page
`hasMore`	boolean	Whether more results exist beyond this page
`backfill_start_index`	integer\|null	Index in `boats` where relaxed-filter backfill results begin (nearby locations / flexible dates), or `null`
`priority_company`	string	Echoes the `priority_company` query value when provided
`facets`	object	Only with `facet_counts=1`: map of feature slug/attribute tag → number of boats in the full matched set carrying it. Zero-count features are omitted.

Boat Object

Field	Type	Description
`id`	string	Unique boat identifier (UUID)
`slug`	string	URL-friendly identifier
`title`	string	Boat name
`boat_type`	string	Type of boat
`capacity`	integer	Maximum guests
`length_ft`	number	Length overall (LOA) in feet
`year`	integer	Year built
`price_per_day`	number	Effective daily rate
`price_from`	number\|null	Lowest seasonal price
`price_to`	number\|null	Highest seasonal price
`discount_percentage`	number\|null	Active discount percentage
`discount_label`	string\|null	Discount label text
`original_price_per_day`	number\|null	Price before discount
`average_rating`	number\|null	Average rating (1-5)
`review_count`	integer	Number of reviews
`location_id`	integer	Location ID
`manufacturer_id`	string\|null	Manufacturer UUID
`company_id`	string	Operator company UUID
`avail_weeks`	integer	Packed availability bitmask (see Availability)
`hero_image_url`	string\|null	Primary image URL
`has_valid_name`	boolean\|null	Whether the boat has a human-readable name
`model`	string\|null	Boat model name
`manufacturer`	object\|null	`{ id, name, slug, logo_url }`
`location`	object	`{ id, city, name, country }`
`amenities`	array	Amenity objects (empty when none linked)
`skippered`	boolean\|string	`true`, `false`, or `"optional"`
`currency`	string	Currency code (e.g. `EUR`)
`internal_discount_pct`	number\|null	Internal discount percentage when applicable
`required_extras`	object\|null	Per-period required extras, only present when a date filter (`d`) is set

Availability

avail_weeks is a packed bitmask of bookable weeks relative to an anchor date. To query availability, pass the d date filter rather than decoding the mask yourself.