GET
# Destination Lookup API

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

## 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](/docs/endpoints/booking/search). 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. 1

#### Lookup Destination ID

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

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

2. 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

 ](/docs/endpoints/booking/search)[ 

### Hotel Details

Get detailed information about specific hotels

 ](/docs/endpoints/booking/hotel-details)

Request

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

Response

```json
{
  "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."
}
```

```json
{
  "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."
}
```