# Booking Location Search ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/booking/location/search` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 3 credits per call | | **Documentation** | https://www.piloterr.com/library/booking-location-search | ## Description Autocomplete a place name, or a Booking city URL such as https://www.booking.com/city/fr/paris.fr.html. The URL is read as the place name. return_page_source is not supported and returns 400. ## Authentication - **Key Name:** `x-api-key` - **Location:** HTTP Header - **Get an API key:** https://app.piloterr.com/register ## Example Request ```bash curl --location --request GET 'https://api.piloterr.com/v2/booking/location/search' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### Suggestions for Paris ```json { "results": [ { "label": "Paris, Île-de-France, France", "title": "Paris", "dest_id": "-1456928", "latitude": 48.8566818237305, "subtitle": "Île-de-France, France", "dest_type": "city", "longitude": 2.35147643089294, "country_code": "fr", "hotels_count": null }, { "label": "Centre de Paris, Paris, Île-de-France, France", "title": "Centre de Paris", "dest_id": "2281", "latitude": 48.8580703735352, "subtitle": "Paris, Île-de-France, France", "dest_type": "district", "longitude": 2.33013200759888, "country_code": "fr", "hotels_count": null }, { "label": "Aéroport de Paris - Roissy - Charles-de-Gaulle, Paris, Île-de-France, France", "title": "Aéroport de Paris - Roissy - Charles-de-Gaulle", "dest_id": "8", "latitude": 49.0070991516113, "subtitle": "Paris, Île-de-France, France", "dest_type": "airport", "longitude": 2.56843996047974, "country_code": "fr", "hotels_count": null } ] } ``` ### Suggestions for Lyon ```json { "results": [ { "label": "Lyon, Rhône-Alpes (Grand Lyon Agglomération), France", "title": "Lyon", "dest_id": "-1448468", "latitude": 45.7577667236328, "subtitle": "Rhône-Alpes (Grand Lyon Agglomération), France", "dest_type": "city", "longitude": 4.83220386505127, "country_code": "fr", "hotels_count": null }, { "label": "Gare de Lyon-Part-Dieu, Lyon, Rhône-Alpes, France", "title": "Gare de Lyon-Part-Dieu", "dest_id": "766", "latitude": 45.761833190918, "subtitle": "Lyon, Rhône-Alpes, France", "dest_type": "landmark", "longitude": 4.85720205307007, "country_code": "fr", "hotels_count": null } ] } ``` ## Documentation ## Overview Queries Booking.com through an unlocked browser session and returns structured JSON. `language` is the Booking locale suffix (`fr`, `en-gb`, `de`, …), not a country domain. `currency` is an ISO 4217 code sent as `selected_currency`. One call returns one page. Returns the same suggestion list as the Booking search box: dest_id, dest_type, label, coordinates and country. There is no pagination object. ## Quickstart ``` https://api.piloterr.com/v2/booking/location/search?query=Paris&language=fr ``` ``` https://api.piloterr.com/v2/booking/location/search?query=Lyon&language=fr ``` ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `query` | string | yes | Free text. Example: Paris, Lyon, CDG. | | `language` | string | no | Booking locale: fr, en-gb, en-us, de, es, it, pt-pt, nl, … Aliases: en, uk, gb, pt, zh, br. | ## Response fields | Field | Type | Description | | --- | --- | --- | | results[].dest_id | string | Booking destination id | | results[].dest_type | string | city, district, airport, landmark, region or country | | results[].label | string | Full suggestion label | | results[].title | string | Short title | | results[].subtitle | string | Region or country line | | results[].country_code | string | ISO country | | results[].latitude | number | Latitude | | results[].longitude | number | Longitude | ## Use cases - Resolve a city name before a hotel search. - Offer an airport or landmark autocomplete. - Disambiguate Paris the city from Disneyland Paris. ## Error codes | Code | Description | | --- | --- | | 400 | Missing query, unknown language, bad currency, or checkout not after check-in. | | 404 | The page was fetched but no matching records could be parsed. | | 500 | The unlocked fetch failed or the page was blocked. |