List Locations

Endpoint

GET /locations

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.

Results are cached for 5 minutes.

Authentication

No authentication required. This is a public endpoint.

Query Parameters

Parameter	Type	Required	Description
`q`	string	No	Search query
`limit`	number	No	Max results (default: 20, max: 200)
`ids`	string	No	Comma-separated location IDs to fetch directly

Example Requests

Search by Name

curl "https://charter.boats/api/locations?q=greece&limit=10"

Fetch by IDs

curl "https://charter.boats/api/locations?ids=4521,4523,4530"

Example Response (Search)

[
  {
    "id": "country:GR",
    "type": "country",
    "name": "Greece",
    "lat": 38.25,
    "lon": 20.48,
    "country": "Greece",
    "country_code": "GR",
    "location": "Greece",
    "boat_count": 1240,
    "poi_count": 3500,
    "location_count": 485
  },
  {
    "id": "state:Western Greece:GR",
    "type": "state",
    "name": "Western Greece",
    "lat": 38.41,
    "lon": 20.62,
    "state": "Western Greece",
    "country": "Greece",
    "country_code": "GR",
    "location": "Western Greece, Greece",
    "boat_count": 320,
    "poi_count": 890,
    "location_count": 62
  },
  {
    "id": 4521,
    "type": "marina",
    "name": "D-Marin Lefkas",
    "lat": 38.8335,
    "lon": 20.7068,
    "city": "Lefkada",
    "state": "Western Greece",
    "country": "Greece",
    "country_code": "GR",
    "location": "Lefkada, Western Greece, Greece",
    "boat_count": 45,
    "poi_count": 12,
    "harbour_category": "marina"
  }
]

Example Response (IDs)

{
  "locations": [
    {
      "id": 4521,
      "name": "D-Marin Lefkas",
      "lat": 38.8335,
      "lon": 20.7068,
      "city": "Lefkada",
      "state": "Western Greece",
      "country": "Greece",
      "country_code": "GR",
      "harbour_category": "marina",
      "poi_count": 12
    }
  ]
}

Response Fields (Search)

Field	Type	Description
`id`	number\|string	Location ID (number) or aggregate key (e.g. `country:GR`)
`type`	string	Result type: `marina`, `city`, `municipality`, `state`, or `country`
`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
`location`	string	Formatted location string
`boat_count`	number	Number of available boats
`poi_count`	number	Number of points of interest
`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, state, municipality, city, marina)
Boat count descending

List Locations

On this page