# Booking Countries ## Overview | Property | Value | |----------|-------| | **Status** | active | | **Method** | `GET` | | **Endpoint** | `/v2/booking/destination/countries` | | **Base URL** | `https://api.piloterr.com` | | **Credit Cost** | 3 credits per call | | **Documentation** | https://www.piloterr.com/library/booking-destination-countries | ## Description Booking.com country index with hotel counts. ## 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/destination/countries' \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' ``` ## Example Response ### French index, page 1 ```json { "results": [ { "url": "https://www.booking.com/country/ba.fr.html", "name": "Bosnie-Herzégovine", "country_code": "ba", "hotels_count": 17956 }, { "url": "https://www.booking.com/country/gi.fr.html", "name": "Gibraltar", "country_code": "gi", "hotels_count": 220 }, { "url": "https://www.booking.com/country/lv.fr.html", "name": "Lettonie", "country_code": "lv", "hotels_count": 7084 } ], "pagination": { "next": "https://www.booking.com/country.fr.html?offset=25", "page": 1, "per_page": 25, "total_pages": 8, "total_results": 195 } } ``` ### English (UK) index, page 2 ```json { "results": [ { "url": "https://www.booking.com/country/ua.en-gb.html", "name": "Ukraine", "country_code": "ua", "hotels_count": 21053 }, { "url": "https://www.booking.com/country/iq.en-gb.html", "name": "Iraq", "country_code": "iq", "hotels_count": 448 }, { "url": "https://www.booking.com/country/ci.en-gb.html", "name": "Côte d'Ivoire", "country_code": "ci", "hotels_count": 1558 } ], "pagination": { "next": "https://www.booking.com/country.en-gb.html?offset=50", "page": 2, "per_page": 25, "total_pages": 8, "total_results": 198 } } ``` ## 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. Reads the country index. Each row is a country name, the two-letter code taken from /country/{code}, the canonical URL, and the hotel count printed on the block when Booking shows one. Pages are slices of 25. ## Quickstart ``` https://api.piloterr.com/v2/booking/destination/countries?language=fr&page=1 ``` ``` https://api.piloterr.com/v2/booking/destination/countries?language=en-gb&page=2 ``` ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `language` | string | no | Booking locale: fr, en-gb, en-us, de, es, it, pt-pt, nl, … Aliases: en, uk, gb, pt, zh, br. | | `page` | integer | no | Page number. Listings use 25 items per page when the source is paginated. | ## Response fields | Field | Type | Description | | --- | --- | --- | | results[].name | string | Country name in the requested language | | results[].country_code | string | Two-letter code | | results[].url | string | Country hub URL | | results[].hotels_count | number|null | Properties mentioned on the index | | pagination | object | page, per_page, total_results, next | ## Use cases - Build a country picker in the user’s language. - Rank countries by listed supply. - Link through to a country hub. ## 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. |