Destinations

Resolve a place name or discover destinations near a coordinate.

Turn a place name or a coordinate into a destination_id usable by /decide and /search/stays. Two endpoints.

POST /v1/destinations/resolve

Resolve a free-text place name to one or more candidates.

Parameters

Parameter	Type	Description
`name` *	string	2-100 chars.
`country`	string	Bias the search.
`type`	enum	`city` \| `neighborhood` \| `airport` \| `poi`.
`language`	enum	en, it, fr, de, es, pt, nl, ko, pl, ja.

* required

Request

curl -X POST https://api.b2a.bluepillow.com/v1/destinations/resolve \
  -H "Authorization: Bearer $B2A_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Rome", "country": "IT", "language": "en"}'

Response 200

{
  "candidates": [
    {
      "id": "dest_5f3a...",
      "name": "Rome",
      "display_name": "Rome, Italy",
      "type": "city",
      "country_code": "IT",
      "country_name": "Italy",
      "location": {"lat": 41.9028, "lon": 12.4964, "default_radius_km": 8.0},
      "accomodations_count": 18432,
      "path_breadcrumb": ["Italy", "Lazio", "Rome"],
      "confidence": 0.98
    }
  ],
  "total_matches": 1,
  "disambiguation_recommended": false
}

POST /v1/destinations/discover-near

Discover destinations within a radius of a coordinate. Useful for region-level intents (e.g. “Tuscany”).

Parameters

Parameter	Type	Description
`lat` *	number	-90..90.
`lon` *	number	-180..180.
`radius_km`	number	Default 5.0.
`type`	enum	Filter by type.

* required

Request

curl -X POST https://api.b2a.bluepillow.com/v1/destinations/discover-near \
  -H "Authorization: Bearer $B2A_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lat": 43.7696, "lon": 11.2558, "radius_km": 25.0, "type": "city"}'

Errors

400 invalid_request · 401 authentication_failed · 404 not_found (resolve only) · 429 rate_limited