Booking.com Destination Lookup API - Convert Location Names to Destination IDs | StayAPI

Overview

GraphQL-Powered

This endpoint uses Booking.com's official GraphQL API to provide fast, reliable destination suggestions with support for multiple location types (cities, districts, airports, landmarks).

The Destination Lookup endpoint uses Booking.com's GraphQL API to resolve 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

Code Examples

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."
}

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

GraphQL-Powered

Uses Booking.com's official AutoComplete GraphQL API for accurate, 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.

Destination Lookup API

Overview

GraphQL-Powered

Updated Behavior

Endpoint URL

Use Case

Parameters

Response Fields

Code Examples

Common Workflow

Two-Step Hotel Search

Lookup Destination ID

Search Hotels

Key Features

GraphQL-Powered

Rich Location Types

Smart Matching

Detailed Labels

Related Endpoints

Hotel Search

Hotel Details