List Locations

Endpoint

GET /locations

Description

A location is an overnight stop — a marina, harbour, or anchorage where you can berth or drop anchor and spend the night aboard your boat.

Search and list locations with boat and POI counts. Returns both individual locations (marinas, anchorages) and aggregated geographic results (cities, states, countries) when a search query matches higher-level regions.

Named sailing regions — "Dalmatia", "the Dodecanese", "the Cyclades" — are also returned (in boats mode only), as type: 'region'. These are not administrative areas and have no location row of their own: they span whichever marinas fall inside the region, including the mainland ports charters depart from. Pass a region row's id as the l parameter on the site, or its name as location_type=text&location_value=… to /api/boats.

Results are cached for 5 minutes.

Authentication

From your server, send X-API-Key: YOUR_API_KEY on every call, like every other Operator API endpoint — without it Cloudflare bot protection answers with an HTML 403 page, not JSON. This exact path (GET /api/locations, not its sub-routes) is also the one read route that answers cross-origin browser calls (Access-Control-Allow-Origin: *) without a key — that is what powers the embeddable search widget's location box. See Authentication.

Query Parameters

Parameter	Type	Required	Description
`q`	string	No	Search query (minimum 2 characters). Ignored when `ids` is supplied
`limit`	number	No	Max results (default: 20, max: 200)
`ids`	string	No	Comma-separated numeric location IDs to fetch directly (returns the `{ "locations": [...] }` shape). Slugs are not accepted here
`mode`	string	No	Which count drives ranking: `boats` (default), `places` (POI count), or `trips` (trip count — returned in the `poi_count` field)
`boat_type`	string	No	When set (in `boats` mode), counts only that boat type and drops marinas with 0 of it

Example Requests

Search by Name

curl "https://charter.boats/api/locations?q=lefkada&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"

Fetch by IDs

curl "https://charter.boats/api/locations?ids=11336" \
  -H "X-API-Key: YOUR_API_KEY"

Example Response (Search)

[
  {
    "id": "municipality:Lefkada Municipality:Ionian Islands:gr",
    "type": "municipality",
    "name": "Lefkada Municipality",
    "lat": 38.703389305882354,
    "lon": 20.712204358823527,
    "city": "Lefkada Municipality",
    "state": "Ionian Islands",
    "country": "Greece",
    "country_code": "gr",
    "location": "Lefkada Municipality, Ionian Islands, Greece",
    "boat_count": 0,
    "poi_count": 0,
    "location_count": 17
  },
  {
    "id": "city:Municipal Unit of Lefkada:null:gr",
    "type": "city",
    "name": "Municipal Unit of Lefkada",
    "lat": 38.81492442857142,
    "lon": 20.704208285714284,
    "city": "Municipal Unit of Lefkada",
    "state": null,
    "country": null,
    "country_code": "gr",
    "location": "Municipal Unit of Lefkada",
    "boat_count": 0,
    "poi_count": 0,
    "location_count": 7
  },
  {
    "id": 11336,
    "type": "marina",
    "name": "D-Marin Lefkas",
    "lat": 38.8289054,
    "lon": 20.7113582,
    "city": "Municipal Unit of Lefkada",
    "state": "Ionian Islands",
    "country": "Greece",
    "country_code": "gr",
    "location": "Municipal Unit of Lefkada, Ionian Islands, Greece",
    "boat_count": 434,
    "poi_count": 0,
    "harbour_category": "marina"
  }
]

Aggregate rows (country/state/municipality/city) carry boat_count: 0 and poi_count: 0 — use location_count to gauge their size. Marina rows carry the real boat_count.

region rows are the exception: they carry a real boat_count, and are only returned when it is greater than zero.

Aggregate ids are built from the row's state and country, and a place whose state is missing gets the literal text null in that slot (city:Municipal Unit of Lefkada:null:gr above). Treat aggregate ids as opaque keys — don't parse them, and don't assume a missing state is rendered as an empty segment.

Example Response (IDs)

When ids is supplied the endpoint returns an object with a locations array (unpublished locations are left out). Each row includes the slug (use it to build /locations/{slug} links), the raw count JSON (boat_counts, poi_counts, trip_counts) alongside the derived boat_count / poi_count scalars.

{
  "locations": [
    {
      "id": 11336,
      "slug": "d-marin-lefkas",
      "name": "D-Marin Lefkas",
      "lat": 38.8289054,
      "lon": 20.7113582,
      "city": "Municipal Unit of Lefkada",
      "state": "Ionian Islands",
      "country": "Greece",
      "country_code": "gr",
      "harbour_category": "marina",
      "boat_counts": { "total": 434, "sailboat": 281, "catamaran": 151, "motorboat": 2 },
      "poi_counts": { "total": 198, "restaurant": 89, "grocery": 24, "parking": 9 },
      "trip_counts": {},
      "boat_count": 434,
      "poi_count": 198
    }
  ]
}

Response Fields (Search)

Field	Type	Description
`id`	number\|string	Location ID (number) or aggregate key (e.g. `municipality:Lefkada Municipality:Ionian Islands:gr`)
`type`	string	Result type: `marina`, `city`, `municipality`, `state`, `country`, or `region`
`name`	string	Location or region name
`lat`	number	Latitude (center point for aggregates)
`lon`	number	Longitude (center point for aggregates)
`city`	string\|null	City name
`state`	string\|null	State or region
`country`	string\|null	Country name
`country_code`	string\|null	ISO country code (lowercase, e.g. `gr`)
`location`	string	Formatted location string
`boat_count`	number	Number of published boats (0 on aggregate rows; 0 on marina rows outside `boats` mode)
`poi_count`	number	Points of interest in `places` mode, trips in `trips` mode, 0 in `boats` mode (always 0 on aggregate rows)
`harbour_category`	string\|null	Type of harbour (`marina` type only)
`location_count`	number	Number of locations in this region (aggregate types only)

Sorting

Results are sorted by:

Type: country, region, state, municipality, city, then marina
Within a type, by the mode's count descending — boat_count in boats mode, poi_count in places / trips mode

With boat_type set (in boats mode), marina rows with none of that type are dropped.

List Locations

On this page