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. This is a public endpoint.

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
`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=4521&category=restaurant"

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&limit=20"

Example Response (Location Mode)

{
  "pois": [
    {
      "id": "poi-uuid-1",
      "osm_id": 987654321,
      "name": "Taverna Nidri",
      "name_en": "Nidri Tavern",
      "category": "restaurant",
      "subcategory": "taverna",
      "lat": 38.8312,
      "lon": 20.7089,
      "address": "Waterfront Road",
      "city": "Lefkada",
      "country": "Greece",
      "phone": "+30 2645 099999",
      "website": "https://example.com",
      "opening_hours": "Mo-Su 12:00-23:00",
      "is_seasonal": true,
      "description": "Traditional Greek taverna on the waterfront",
      "cuisine": "greek",
      "image_url": "https://example.com/taverna.jpg",
      "rating": 4.7,
      "distance_meters": 350,
      "walking_time_minutes": 4
    }
  ],
  "total": 1,
  "location_id": 4521
}

Example Response (Region Mode)

{
  "pois": [
    {
      "id": "poi-uuid-2",
      "name": "Port Fuel Station",
      "category": "fuel",
      "lat": 38.7420,
      "lon": 20.7380,
      "rating": 4.2,
      "distance_meters": 50,
      "walking_time_minutes": 1
    }
  ],
  "total": 245,
  "hasMore": true,
  "location_type": "country",
  "location_value": "gr"
}

Response Fields

Field	Type	Description
`pois`	array	List of POIs
`total`	number	Total number of matching POIs
`hasMore`	boolean	Whether more results exist (region mode with pagination)
`location_id`	number	Echoed location ID (location mode)
`center`	object	Echoed search center (coordinate 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)
`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
`cuisine`	string\|null	Cuisine type (restaurants only)
`image_url`	string\|null	Image URL
`rating`	number\|null	Rating
`distance_meters`	number\|null	Distance from the reference location
`walking_time_minutes`	number\|null	Estimated walking time

Error Responses

400 Bad Request

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

Search POIs

On this page