# Search for transfers Beta **Use the /transfers/search endpoint to search for available airport transfers and point-to-point rides. Display the returned options to travellers and redirect them to Booking.com to complete the booking.** Transfers API – Beta access The Transfers API is currently available to selected partners as part of the Beta collection. - **Active development:** The API is under active development and may change. - **Available flow:** Search, look and redirect is currently available through the [/transfers/search](/demand/docs/open-api/3.2-beta/demand-api/transfers/searchtransfers) endpoint. - **Access:** Access may be restricted to approved partners.Contact your Partnership Manager to request access. - **Updates:** Check the [Demand API Changelog](/demand/docs/whats-new/changelog) regularly for the latest changes. The /transfers/search endpoint returns resolved journey details, available vehicle options, capacity, prices, cancellation information, an expiry time, and a Booking.com URL for each vehicle option. ## Endpoint overview Use the following operation to search for transfers: | Property | Value | | --- | --- | | Method | `POST` | | Endpoint | [/transfers/search](/demand/docs/open-api/3.2-beta/demand-api/transfers/searchtransfers) | | Authentication | Demand API bearer-token authentication. [See the authentication guide](/demand/docs/development-guide/authentication) for details. | | Required headers | `Authorization: Bearer ` and `X-Affiliate-Id: ` | | Request body | JSON | | Response | Available transfers and redirect URLs | Admonition name For authentication details, see [Authentication and authorisation](/demand/docs/development-guide/authentication). ## How the integration works 1. Collect the traveller’s journey, passenger, currency, language, and booker-country details. 2. Send a request to /transfers/search. 3. Display the returned resolved route, vehicle options, prices, capacity, and cancellation policy. 4. Check that the results have not expired before displaying them. 5. Let the traveller select a vehicle option. 6. Redirect the traveller using the `url` returned for that selected option. 7. The traveller completes the reservation on Booking.com. This is a [Search, look and redirect flow](/demand/docs/development-guide/application-flows/search-look-redirect). The endpoint does not create a booking through the Demand API. ## Request The request body is JSON and must contain: * `route` * `passengers` * `currency` * `booker.country` The optional `language` field defaults to `en-gb`. ### Minimum one-way request ```json { "route": { "legs": [ { "pickup": { "location": { "airport": "AMS" }, "datetime": "2026-09-27T14:30:00" }, "dropoff": { "location": { "coordinates": { "latitude": 52.3676, "longitude": 4.9041 } } } } ] }, "passengers": 3, "currency": "EUR", "booker": { "country": "ro" } } ``` ### Required fields | Field | Format | Description | | --- | --- | --- | | `route.legs` | Array | The journey legs in travel order. One item represents a one-way journey; two items represent a return journey. | | `passengers` | Integer, minimum 1 | The number of passengers travelling. The response only includes vehicles with sufficient passenger capacity. | | `currency` | ISO 4217 currency code | Currency used for prices in the response. Supported currencies are listed below. | | `booker.country` | ISO 3166-1 alpha-2 country code | Booker’s country, used for pricing context and applicable tax and fee display requirements. | ### Optional fields | Field | Format | Description | | --- | --- | --- | | `language` | Language identifier, for example `es` | The language used for the search results and Booking.com redirect URL. Defaults to `en-gb`. | ### Define the journey Use `route.legs` to define the journey. * A one-way journey contains one leg. * A return journey contains two legs. * Legs must be in travel order. * Every leg must include its own pickup location, pickup datetime, and drop-off location. #### One-way journey The first leg must include: * The pick-up location. * The local pick-up date and time. * The drop-off location. ```json { "route": { "legs": [ { "pickup": { "location": { "airport": "AMS" }, "datetime": "2026-12-12T14:30:00" }, "dropoff": { "location": { "coordinates": { "latitude": 52.3676, "longitude": 4.9041 } } } } ] } } ``` #### Return journey A return journey contains two legs: * The outbound leg. * The return leg. Both legs must include their own pick-up location, pick-up date and time, and drop-off location. For a standard return journey, the second leg’s locations must match the outbound leg in reverse: * Return pickup = outbound drop-off. * Return drop-off = outbound pickup. Example: ```json { "route": { "legs": [ { "pickup": { "location": { "airport": "MAN" }, "datetime": "2026-12-12T10:00:00" }, "dropoff": { "location": { "google_place_id": "ChIJVYR0dR3hxUcRwz_xGKN6B_s" } } }, { "pickup": { "location": { "google_place_id": "ChIJVYR0dR3hxUcRwz_xGKN6B_s" }, "datetime": "2026-12-15T16:15:00" }, "dropoff": { "location": { "airport": "MAN" } } } ] } } ``` The return pickup datetime must be later than the outbound pickup datetime. The API may also reject a return pickup that is too soon after the outbound pickup. ### Specify journey locations Each pick-up or drop-off location must contain exactly one of the following properties: | Field | Format | Description | | --- | --- | --- | | `airport` | IATA airport code | Identifies an airport, for example `AMS` for Amsterdam Airport Schiphol. | | `google_place_id` | Google Place ID | Identifies a place using its Google Place ID. | | `coordinates` | Object | Identifies a location using geographic coordinates. | Do not combine location types. For example, a location must not contain both `airport` and `google_place_id` or `coordinates`. #### Airport Use `airport` to identify a location by its IATA airport code. ```json { "location": { "airport": "AMS" } } ``` #### Google Place ID Use `google_place_id` to identify a location by its Google Place ID. ```json { "location": { "google_place_id": "ChIJVYR0dR3hxUcRwz_xGKN6B_s" } } ``` #### Coordinates Use `coordinates` to identify a location by latitude and longitude. ```json { "location": { "coordinates": { "latitude": 52.3676, "longitude": 4.9041 } } } ``` Use accurate coordinates and a resolvable Google Place ID. The API may reject a route when either location cannot be resolved or is outside the supported service region. ### Specify pickup date and time Use `pickup.datetime` for the local pickup date and time of each leg. Use the following format: `YYYY-MM-DDTHH:mm:ss` For example: ```json { "datetime": "2026-12-12T14:30:00" } ``` Do not include a time zone or UTC offset. The API interprets the value using the local time zone of the pick-up location. For a return journey, provide a separate `pickup.datetime` for each leg. ### Specify the number of passengers Use `passengers` to specify the number of travellers requiring the transfer. ```json { "passengers": 3 } ``` The value must be at least `1`. The response contains vehicle options with sufficient passenger capacity for the requested number of passengers. Use the returned `max_passengers` value when displaying each option. ### Specify currency and language #### Currency Use `currency` to specify the currency used for prices in the response. The current schema lists these ISO 4217 currency codes: `AED`, `AUD`, `CAD`, `CHF`, `CLP`, `CNY`, `CZK`, `DKK`, `EGP`, `EUR`, `GBP`, `HKD`, `HUF`, `IDR`, `ILS`, `INR`, `ISK`, `JPY`, `KRW`, `MAD`, `MXN`, `NOK`, `NZD`, `PLN`, `QAR`, `RON`, `RSD`, `SAR`, `SEK`, `SGD`, `THB`, `TRY`, `TWD`, `UAH`, `USD` and `ZAR`. Example: ```json { "currency": "EUR" } ``` * If you provide an unsupported currency, the API returns a 400 Bad Request response with an `invalid_parameter` error. The supported currencies may change over time. Do not hardcode the list in your integration. Handle an `invalid_parameter` response gracefully if a currency is no longer supported. #### Language Use `language` to specify the language used for the search results and Booking.com redirect URL. ```json { "language": "es" } ``` If you omit `language`, the API defaults to `en-gb`. ### Specify the booker Use `booker.country` to provide the booker’s two-letter country code. ```json { "booker": { "country": "ro" } } ``` The booker country provides context for pricing and for displaying applicable taxes and fees. ## Transfers API response A successful response contains a `request_id` and a `data` object. | Field | Description | | --- | --- | | `request_id` | Unique identifier for the request. Provide it when contacting support. | | `data.currency` | Currency used for the returned prices. | | `data.expires_at` | Time at which the search results expire. | | `data.route` | Resolved journey route and estimated leg details. | | `data.vehicle_options` | Available vehicle options, capacities, prices, and redirect URLs. | | `data.cancellation_policy` | Cancellation policy applying to the available vehicle options. | ### Example response ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "currency": "EUR", "expires_at": "2026-12-12T10:30:00Z", "route": { "legs": [ { "pickup": { "datetime": "2026-12-12T14:30:00", "location": { "name": "Amsterdam Airport Schiphol (AMS)", "address": "Evert van de Beekstraat 202, 1118 CP Schiphol, Netherlands", "city": "Schiphol", "country": "nl", "coordinates": { "latitude": 52.3105, "longitude": 4.7683 }, "iata": "AMS" } }, "dropoff": { "location": { "name": "Booking.com HQ", "address": "Herengracht 597, 1017 CE Amsterdam, Netherlands", "city": "Amsterdam", "country": "nl", "coordinates": { "latitude": 52.3676, "longitude": 4.9041 }, "iata": null } }, "duration": null, "distance": null } ] }, "vehicle_options": [ { "name": "Standard", "max_passengers": 4, "max_luggage": 3, "price": 45.50, "url": "https://taxis.booking.com/search/..." } ], "cancellation_policy": { "type": "free_cancellation", "details": { "context": "before_pickup", "duration": "PT48H" } } } } ``` ### Interpret the response #### Search result expiry `expires_at` is the expiry timestamp for the search results. It uses a timezone-aware date-time, for example: ```json { "expires_at": "2026-09-20T10:30:00Z" } ``` After expiry, prices and availability may change. Run a new search before showing stale results or relying on a previously returned option. #### Resolved route The response contains the resolved route and its journey legs. Each leg includes: * The pickup datetime and resolved pickup location. * The resolved drop-off location. * `duration`, an estimated travel time in minutes, or `null`. * `distance`, an estimated distance in kilometres, or `null`. Resolved pickup and drop-off locations include: * `name` * `address` * `country` * `coordinates` * `city`, which may be `null` * `iata`, which contains a three-letter airport code for airports and is `null` for non-airport locations The pickup datetime is expressed in the local time of the pickup location and does not include a timezone or UTC offset. The response does not include a separate drop-off datetime. The current transfer search returns `null` for both `duration` and `distance`, so a drop-off time cannot currently be derived from the response. If a future response provides a duration, any derived drop-off time must be presented as an estimate. #### Vehicle options The `vehicle_options` array contains the available vehicle options for the journey. Options are sorted by price, cheapest first. Each option includes: | Field | Description | | --- | --- | | `name` | The display name of the vehicle option. | | `max_passengers` | The maximum number of passengers the vehicle can accommodate. | | `max_luggage` | The maximum number of standard suitcases the vehicle can accommodate. | | `price` | The total price in the requested currency. For a return journey, this covers both the outbound and return legs. | | `url` | The Booking.com URL for the selected vehicle option. Use the returned URL unchanged. | #### Vehicle options The `vehicle_options` array contains the available vehicle options for the journey. Each option includes: | Field | Description | | --- | --- | | `name` | The display name of the vehicle option. | | `max_passengers` | The maximum number of passengers the vehicle can accommodate. | | `max_luggage` | The maximum number of standard suitcases the vehicle can accommodate. | | `price` | The total price in the requested currency. | | `url` | The Booking.com URL for the selected vehicle option. | For a return journey, `price` covers both the outbound and return legs. #### Cancellation policy The `cancellation_policy.type` value is one of: * `free_cancellation` - Free cancellation is available under the conditions in `details`. * `non_refundable` - The transfer is non-refundable. For free cancellation, `details` contains the cancellation context and an ISO 8601 duration. For example: ```json { "cancellation_policy": { "type": "free_cancellation", "details": { "context": "before_pickup", "duration": "PT48H" } } } ``` In this example, `PT48H` means that free cancellation is available up to 48 hours before pick-up. For a return journey, the cancellation policy applies to both legs. ### Redirect travellers to Booking.com Each vehicle option includes a `url` that redirects the traveller to Booking.com with that vehicle option selected. ```json { "name": "Standard", "max_passengers": 4, "max_luggage": 3, "price": 45.50, "url": "https://taxis.booking.com/search/..." } ``` Use the returned URL to redirect the traveller to Booking.com and continue with the selected vehicle option. Use the redirect URL returned for the selected vehicle option rather than constructing a Booking.com transfers URL yourself. ## Best practices ✅ **Use accurate location data** * Use the most appropriate supported location type for each pick-up and drop-off point. * Specify exactly one of `airport`, `google_place_id` or `coordinates` for each location. * Provide locations for both legs of a return journey. * For a standard return journey, provide the outbound locations in reverse for the return leg. ✅ **Use local pick-up times** * Provide `pickup.datetime` in the local time of the pick-up location. * Do not include a time zone or UTC offset. * Provide a separate pick-up date and time for each journey leg. ✅ **Keep availability and prices up to date** * Check `expires_at` before displaying previously retrieved search results. * Run a new search after the results expire. * Do not assume that prices or availability remain unchanged. ✅ **Display vehicle capacity accurately** * Use `max_passengers` and `max_luggage` when displaying vehicle options to travellers. * Do not infer vehicle capacity from the vehicle category or display name. ✅ **Use the returned redirect URL** * Redirect travellers using the `url` returned for their selected vehicle option. * Do not construct or modify Booking.com transfers booking URLs. Curious to know more? * Refer to the /transfers/search API reference for the complete request and response schema. * Check the [Changelog](/demand/docs/whats-new/changelog) for the latest transfers API updates.