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, 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

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

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 location IDs to fetch directly (returns the `{ "locations": [...] }` shape)
`mode`	string	No	Which count drives ranking: `boats` (default), `places`, or `trips`
`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"

Fetch by IDs

curl "https://charter.boats/api/locations?ids=11336"

Example Response (Search)

[
  {
    "id": "municipality:Lefkada Municipality:Ionian Islands:gr",
    "type": "municipality",
    "name": "Lefkada Municipality",
    "lat": 38.69734746666667,
    "lon": 20.713507155555558,
    "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": 27
  },
  {
    "id": "city:Municipal Unit of Lefkada:Ionian Islands:gr",
    "type": "city",
    "name": "Municipal Unit of Lefkada",
    "lat": 38.748633411111115,
    "lon": 20.72957658888889,
    "city": "Municipal Unit of Lefkada",
    "state": "Ionian Islands",
    "country": "Greece",
    "country_code": "gr",
    "location": "Municipal Unit of Lefkada, Ionian Islands, Greece",
    "boat_count": 0,
    "poi_count": 0,
    "location_count": 9
  },
  {
    "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": 395,
    "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.

Example Response (IDs)

When ids is supplied the endpoint returns an object with a locations array. Each row includes the raw count JSON (boat_counts, poi_counts, trip_counts) alongside the derived boat_count / poi_count scalars.

{
  "locations": [
    {
      "id": 11336,
      "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": 395, "sailboat": 251, "catamaran": 143, "motorboat": 1 },
      "poi_counts": { "total": 186, "restaurant": 81, "parking": 42, "grocery": 21 },
      "trip_counts": {},
      "boat_count": 395,
      "poi_count": 186
    }
  ]
}

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 available boats (0 on aggregate rows)
`poi_count`	number	Number of points of interest (only populated in `places` mode)
`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:

Locations with boats first
Aggregate types first (country, region, state, municipality, city, marina)
Boat count descending

List Locations

On this page