GET

Destination Lookup API

Convert free-form location names into Booking.com destination IDs for precise hotel searches.

Copy for your AI agent

Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.

Overview

Live Booking.com Suggestions

This endpoint returns fast, reliable Booking.com destination suggestions with support for multiple location types (cities, districts, airports, landmarks).

The Destination Lookup endpoint resolves free-form location queries (like "Barcelona", "Paris", or "New York") into destination IDs and types. It provides instant, accurate destination suggestions including cities, districts, airports, and landmarks - useful when you don't know the exact destination ID but want to search for hotels in a specific location.

Updated Behavior

The API now returns success: true whenever a valid dest_id is found and returned. When multiple destinations match, it automatically uses the first suggestion as default while still returning all options. The success field now simply indicates whether a usable destination ID was found.

Endpoint URL

GET https://api.stayapi.com/v1/booking/destinations/lookup

Use Case

Use this endpoint to find the dest_id before calling the Hotel Search endpoint. This two-step workflow allows users to search by familiar location names instead of numeric IDs.

Parameters

Parameter	Type	Required	Description
query	string	Required	Location name to search for (e.g., "Barcelona", "Paris", "New York", "Phuket")
language	string	Optional	Language code for results (default: "en-us"). Examples: "en-us", "fr", "de", "es"

Response Fields

Field	Type	Description
success	boolean	True when a valid dest_id is found and returned, false only when no destinations found or an error occurs
query	string	The original query string provided
dest_id	integer	Booking.com destination ID (populated with first suggestion when multiple matches exist)
dest_type	string	Type of destination: "CITY", "REGION", "DISTRICT", "AIRPORT", "LANDMARK" (populated with first suggestion when multiple matches exist)
normalized_query	string	Normalized location name from Booking.com (populated with first suggestion's label when multiple matches exist)
suggestions	array	List of alternative destinations if query is ambiguous
message	string	Descriptive message about the result

Common Workflow

Two-Step Hotel Search

1

Lookup Destination ID

Call this endpoint with a location name to get the dest_id.

GET /v1/booking/destinations/lookup?query=Barcelona
2

Search Hotels

Use the returned dest_id to search for hotels.

GET /v1/booking/search?dest_id=20014181&dest_type=CITY

💡 Pro Tip: Cache destination IDs on your end to avoid repeated lookups for popular locations.

Key Features

Live Suggestions

Returns Booking.com's own real-time destination suggestions.

Rich Location Types

Returns cities, districts, airports, landmarks, and regions - not just cities. Get comprehensive location suggestions.

Smart Matching

Single unambiguous matches return destination ID directly. Multiple matches return suggestions for user selection.

Detailed Labels

Returns up to 5 suggestions with full location labels (e.g., "Paris, Ile de France, France") to help users choose correctly.

Related Endpoints

Hotel Search

Search for hotels using the dest_id from this endpoint

Hotel Details

Get detailed information about specific hotels

Request

curl -X GET "https://api.stayapi.com/v1/booking/destinations/lookup?query=Barcelona" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  'https://api.stayapi.com/v1/booking/destinations/lookup?query=Barcelona',
  {
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Destination ID: ${data.dest_id}, Type: ${data.dest_type}`);

import requests

url = "https://api.stayapi.com/v1/booking/destinations/lookup"
headers = {
    "x-api-key": "YOUR_API_KEY"
}
params = {
    "query": "Barcelona"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

# dest_id and dest_type are always populated when destinations are found
if data["dest_id"]:
    print(f"Destination ID: {data['dest_id']}")
    print(f"Type: {data['dest_type']}")

    # Check if multiple suggestions exist
    if data.get("suggestions"):
        print(f"Note: {len(data['suggestions'])} suggestions found, using first as default")
else:
    print(f"No destinations found: {data['message']}")'

Response

{
  "success": true,
  "query": "Barcelona",
  "normalized_query": "Barcelona, Catalonia, Spain",
  "dest_id": -372490,
  "dest_type": "CITY",
  "suggestions": [],
  "message": "Resolved destination"
}

{
  "success": true,
  "query": "Barcelona",
  "normalized_query": "Barcelona, Catalonia, Spain",
  "dest_id": -372490,
  "dest_type": "CITY",
  "suggestions": [
    {
      "dest_id": -372490,
      "dest_type": "CITY",
      "label": "Barcelona, Catalonia, Spain"
    },
    {
      "dest_id": 2287,
      "dest_type": "DISTRICT",
      "label": "Downtown Barcelona, Barcelona, Catalonia, Spain"
    },
    {
      "dest_id": 41,
      "dest_type": "AIRPORT",
      "label": "Barcelona El Prat Airport, Barcelona, Catalonia, Spain"
    },
    {
      "dest_id": 1288,
      "dest_type": "DISTRICT",
      "label": "Gothic Quarter, Barcelona, Catalonia, Spain"
    },
    {
      "dest_id": 203351,
      "dest_type": "LANDMARK",
      "label": "Sants Railway Station, Barcelona, Catalonia, Spain"
    }
  ],
  "message": "Multiple destinations found. Using first suggestion as default. You can select a different one if needed."
}

{
  "success": false,
  "query": "InvalidLocation123",
  "normalized_query": null,
  "dest_id": null,
  "dest_type": null,
  "suggestions": [],
  "message": "Unable to resolve destination. Try a more specific query or use suggestions if available."
}