Destinations

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.

Parameter	Type	Description
namerequired	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.

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.

Parameter	Type	Description
latrequired	number	-90..90.
lonrequired	number	-180..180.
radius_km	number	Default 5.0.
type	enum	Filter by destination type.

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