Search POIs

Endpoint

GET /pois/search

Search for points of interest (restaurants, shops, fuel stations, etc.) near a location. Supports three search modes: by location ID, by coordinates with radius, or by geographic region (country, state, city).

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

Use one of the three search modes:

Mode 1: By Location ID

Parameter	Type	Required	Description
`location_id`	number	Yes	Location ID to find nearby POIs
`category`	string	No	Filter by POI category
`minRating`	number	No	Minimum rating filter
`limit`	number	No	Max results (default: 50, max: 200)

Mode 2: By Coordinates

Parameter	Type	Required	Description
`lat`	number	Yes	Latitude
`lon`	number	Yes	Longitude
`radius`	number	No	Search radius in km (default: 1, max: 10)
`category`	string	No	Filter by POI category
`minRating`	number	No	Minimum rating filter
`limit`	number	No	Max results (default: 50, max: 200)

Mode 3: By Region

Parameter	Type	Required	Description
`location_type`	string	Yes	One of: `country`, `state`, `city`, `municipality`
`location_value`	string	Yes	Region name or country code
`country_code`	string	No	ISO country code (narrows state/city/municipality results)
`category`	string	No	Filter by POI category
`q`	string	No	Filter by name (matches `name` or `name_en`)
`minRating`	number	No	Minimum rating filter
`limit`	number	No	Max results (default: 50, max: 200)
`offset`	number	No	Pagination offset (default: 0)

Example Requests

By Location

curl "https://charter.boats/api/pois/search?location_id=11336&category=parking"

By Coordinates

curl "https://charter.boats/api/pois/search?lat=38.83&lon=20.71&radius=2"

By Country

curl "https://charter.boats/api/pois/search?location_type=country&location_value=gr&category=restaurant&limit=20"

Example Response (Location Mode)

{
  "pois": [
    {
      "id": "c72f95e7-5fc1-4b5e-ab47-be494a849858",
      "osm_id": 1122536808,
      "name": "Parking",
      "name_en": null,
      "category": "parking",
      "subcategory": "parking",
      "lat": 38.8285667,
      "lon": 20.7114899,
      "address": null,
      "city": null,
      "country": null,
      "phone": null,
      "website": null,
      "opening_hours": null,
      "is_seasonal": false,
      "description": null,
      "cuisine": null,
      "image_url": null,
      "image_attribution": null,
      "rating": null,
      "nearest_location_name": "D-Marin Lefkas",
      "poi_id": "c72f95e7-5fc1-4b5e-ab47-be494a849858",
      "distance_meters": 39,
      "walking_time_minutes": 1,
      "location_name": "D-Marin Lefkas"
    }
  ],
  "total": 1,
  "location_id": 11336
}

Example Response (Region Mode)

{
  "pois": [
    {
      "id": "ffeb0e30-47de-4c5b-a0e3-9c5bba7acdf9",
      "osm_id": 8838655415,
      "name": "Delfini Hotel Appartments",
      "name_en": null,
      "category": "restaurant",
      "subcategory": "restaurant",
      "lat": 36.9951066,
      "lon": 24.675694,
      "address": null,
      "city": null,
      "country": null,
      "phone": null,
      "website": null,
      "opening_hours": null,
      "is_seasonal": false,
      "description": "The restaurant at Delfini Hotel serves up a free breakfast buffet...",
      "cuisine": null,
      "image_url": "https://dynamic-media-cdn.tripadvisor.com/media/photo-o/01/ef/75/f9/getlstd-property-photo.jpg",
      "image_attribution": null,
      "rating": 9.8,
      "is_active": true,
      "nearest_location_name": "Sifnos",
      "poi_id": "ffeb0e30-47de-4c5b-a0e3-9c5bba7acdf9",
      "distance_meters": 663,
      "location_name": "Sifnos"
    }
  ],
  "total": 20,
  "hasMore": true,
  "location_type": "country",
  "location_value": "gr"
}

Ratings are on a 0–10 scale (e.g. 9.8), not 0–5. The total field is the size of the returned page, not the global count.

Response Fields

Field	Type	Description
`pois`	array	List of POIs
`total`	number	Number of POIs in this response (page size, not a global count)
`hasMore`	boolean	Whether more results exist (region mode with pagination)
`location_id`	number	Echoed location ID (location mode)
`radius_km`	number	Echoed search radius (coordinate mode)
`location_type`	string	Echoed location type (region mode)
`location_value`	string	Echoed location value (region mode)

POI Fields

Field	Type	Description
`id`	string	POI ID (UUID)
`poi_id`	string	Same as `id` (convenience alias)
`osm_id`	number\|null	OpenStreetMap ID
`name`	string	POI name (local language)
`name_en`	string\|null	English name
`category`	string	POI category
`subcategory`	string\|null	More specific category
`lat`	number	Latitude
`lon`	number	Longitude
`address`	string\|null	Street address
`city`	string\|null	City
`country`	string\|null	Country
`phone`	string\|null	Phone number
`website`	string\|null	Website URL
`opening_hours`	string\|null	Opening hours (OSM format)
`is_seasonal`	boolean\|null	Whether the business is seasonal
`description`	string\|null	Description (markdown)
`cuisine`	string\|null	Cuisine type (restaurants only)
`image_url`	string\|null	Image URL
`image_attribution`	string\|null	Image attribution text
`rating`	number\|null	Rating on a 0–10 scale
`is_active`	boolean	Active flag (present in region mode only)
`nearest_location_name`	string\|null	Name of the nearest charter location
`location_name`	string\|null	Same nearest-location name (convenience alias)
`distance_meters`	number\|null	Distance from the reference location
`walking_time_minutes`	number\|null	Estimated walking time (location mode only)

Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Either q, location_id, or lat/lon coordinates required"
}

An invalid category value also returns 400 (Invalid category: <value>).

Search POIs

On this page