Map API

Map pin retrieval with optional radius and category filters, plus planned POI summary callouts and distance/travel-time calculations.

Status

GET /api/v1/map/pois is live. GET /api/v1/map/pois/:id/summary and GET /api/v1/map/pois/:id/distance remain planned under KUB-139, KUB-142, and KUB-145.

---

List Map POIs

GET /api/v1/map/pois

Returns published places with a known location, suitable for rendering lightweight map pins. Supports optional radius filtering around a center coordinate and optional category filtering.

When lat and lng are provided together, the route applies a radius filter. Providing only one coordinate returns 400 missing_coordinates, and malformed coordinate values return 400 invalid_coordinates. Without coordinates, it returns up to 500 published, location-tagged places ordered by ascending place id.

Query Parameters

Parameter	Type	Required	Description
lat	number	No	Center latitude for radius filtering
lng	number	No	Center longitude for radius filtering
radius	number	No	Radius in metres when lat and lng are present
category_id	integer	No	Filter by category id

Response

{
	"data": [
		{
			"id": "42",
			"name": "Trafalgar Falls",
			"slug": "trafalgar-falls",
			"lat": 15.3167,
			"lng": -61.3667,
			"category_id": "3",
			"category_slug": "waterfalls",
			"place_kind": "poi"
		}
	]
}

category_id in the response is a stringified numeric id.

The route returns at most 500 pins and responds with 400 missing_coordinates, 400 invalid_coordinates, or 400 invalid_category_id when the query parameters are invalid.

Related: KUB-141.

---

POI Summary (Map Callout)

GET /api/v1/map/pois/:id/summary

Lightweight data for the map callout card shown when a pin is tapped. Designed to be fast and minimal.

Response

{
	"data": {
		"id": "place_boiling_lake",
		"name": "Boiling Lake",
		"category": { "id": "cat_nature", "name": "Nature" },
		"short_description": "One of the world's largest boiling lakes.",
		"thumbnail": "https://cdn.kubuli.com/places/boiling-lake-thumb.jpg",
		"lat": 15.3102,
		"lng": -61.2884,
		"distance_km": 8.4
	}
}

distance_km requires the caller to pass lat + lng query parameters:

GET /api/v1/map/pois/:id/summary?lat=15.3014&lng=-61.3874

Related: KUB-139.

---

Distance & Travel Time

GET /api/v1/map/pois/:id/distance

Returns estimated travel distance and time from a given coordinate to the POI.

Query Parameters

Parameter	Type	Required	Description
lat	number	Yes	Origin latitude
lng	number	Yes	Origin longitude
mode	walking | driving	No	Travel mode (default: walking)

Response

{
	"data": {
		"poi_id": "place_boiling_lake",
		"distance_km": 8.4,
		"duration_minutes": 110,
		"mode": "walking"
	}
}

Related: KUB-145.