{ "openapi": "3.0.3", "info": { "title": "Booking.com Real-time Data API", "version": "1.0.0", "description": "Live Booking.com data in clean JSON by Data Forge - hotels (search, full details, live room prices, reviews, photo galleries), plus flights, attractions & activities, car rentals and airport taxis, all under one API. Adaptive inputs accept a city name, slug, ID or Booking.com URL. Every response uses one envelope: { success, data, error }." }, "servers": [ { "url": "https://api.usp-ultimate.co", "description": "Data Forge API base" } ], "tags": [ { "name": "Hotels", "description": "Hotel search, details, live room prices, reviews, photos, destinations" }, { "name": "Flights", "description": "Flight search and cheapest-destination discovery" }, { "name": "Attractions", "description": "Attractions & activities search, products, availability, reviews" }, { "name": "Cars", "description": "Car rental search, vehicle and supplier details" }, { "name": "Taxi", "description": "Airport taxi / transfer pricing and autocomplete" }, { "name": "Utilities", "description": "Currencies, languages, exchange rates and universal Booking URL parser" } ], "components": { "schemas": { "ApiResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "description": "Endpoint payload", "nullable": true }, "error": { "type": "string", "nullable": true, "example": null } } } } }, "paths": { "/api/v1/booking/attractions/autocomplete": { "get": { "tags": [ "Attractions" ], "summary": "Attractions autocomplete", "description": "Search suggestions for attraction destinations, products, and points of interest.", "operationId": "attractionsAutocomplete", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "ufi", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional city UFI to scope results (int or numeric string)", "nullable": true }, "description": "Optional city UFI to scope results (int or numeric string)" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 1, "default": 4 } } ] } }, "/api/v1/booking/attractions/availability": { "get": { "tags": [ "Attractions" ], "summary": "Attraction availability (calendar + timeslots, single date OR range)", "description": "Get availability calendar + timeslots for a product, single-date or for an inclusive date range (NEW 2026-05-18 range fan-out — Booking's getAvailability is single-date only on the server, so we fan out per-day in parallel server-side, saving the client N round trips). Response shape: - calendar: {available_dates, cheapest_prices, is_continuously_available, synthesized_calendar} — synthesized_calendar is populated only when the product is continuously available AND a date range was requested; it gives clients per-date representative prices without N round-trips. - timeslots: [...] (populated when start_date alone is given). - range_timeslots: [{date, timeslots, error?}] (one entry per day in the range — populated only when BOTH start_date+end_date given). Params: slug (str, required) — product slug; start_date (str, optional, YYYY-MM-DD) — single date OR range start; end_date (str, optional, YYYY-MM-DD) — range end (inclusive, max 31 days).", "operationId": "attractionsAvailability", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "slug", "in": "query", "required": true, "schema": { "type": "string", "description": "Product slug" }, "description": "Product slug" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "description": "YYYY-MM-DD — single date OR range start", "nullable": true }, "description": "YYYY-MM-DD — single date OR range start" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "description": "YYYY-MM-DD — range end (inclusive, max 31 days)", "nullable": true }, "description": "YYYY-MM-DD — range end (inclusive, max 31 days)" } ] } }, "/api/v1/booking/attractions/destinations": { "get": { "tags": [ "Attractions" ], "summary": "All attraction destinations", "description": "List all cities worldwide with available attractions. Use UFI values in /search.", "operationId": "attractionsDestinations", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/v1/booking/attractions/location": { "get": { "tags": [ "Attractions" ], "summary": "Attraction location details", "description": "Get city details for attractions: name, count, image, coordinates. Adaptive ufi: accepts int, numeric string, text city name, or URL.", "operationId": "attractionsLocation", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "ufi", "in": "query", "required": true, "schema": { "type": "string", "description": "City UFI: int, text city name, or URL (adaptive)" }, "description": "City UFI: int, text city name, or URL (adaptive)" } ] } }, "/api/v1/booking/attractions/parse": { "get": { "tags": [ "Attractions" ], "summary": "Universal URL parser", "description": "Parse any Booking attractions URL and auto-route to the right endpoint. Supported URL patterns: - booking.com/attractions/{cc}/{product-slug}.html → product detail; - booking.com/attractions/{cc}/{city-slug}.html → city search; - booking.com/attractions/searchresults.html?ufi=... → search results. Returns {type: 'product'|'city'|'search'|'unknown', data: {...}}. Params: url (str, required) — any Booking.com attractions URL.", "operationId": "attractionsParse", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "Booking.com attractions URL" }, "description": "Booking.com attractions URL" } ] } }, "/api/v1/booking/attractions/product": { "get": { "tags": [ "Attractions" ], "summary": "Attraction product detail (PDP)", "description": "Get full product page detail for a single attraction. Returns name, description, all photos, all offers/ticket types, cancellation policy, addresses (attraction/meeting/pickup), highlights, audio/guide languages, supplier info, FAQs, on-site requirements. Params: slug (str, required) — product slug from /search results (e.g. 'prjyfitkuhfz-one-day-admission-to-disneylandr-paris').", "operationId": "attractionsProduct", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "slug", "in": "query", "required": true, "schema": { "type": "string", "description": "Product slug (from /search results)" }, "description": "Product slug (from /search results)" } ] } }, "/api/v1/booking/attractions/reviews": { "get": { "tags": [ "Attractions" ], "summary": "Attraction reviews", "description": "Get reviews for a single attraction product. Returns total count, reviews, filter facets, sorters, and sort_by_used. Each review now includes (NEW 2026-05-18): date_ms (Unix ms), date_iso (ISO 8601 UTC), is_approved (moderation), photos[] (user-uploaded with small/large URLs), category_ratings[] (per-category breakdown), and user.country_code (cc1 ISO). Params: product_id (str, required) — product ID from /search (e.g. 'PRjYfiTKUhFz'); sort_by (str, optional) — most_relevant (default) | newest | oldest | highest_rating | lowest_rating. DIFFERENT sort_by values yield DIFFERENT review subsets — client can rotate through all 5 to retrieve ~30-40 distinct reviews per product. offset (int, optional, default=0) — RESERVED; Booking's getReviewsV3 caps at 10 reviews per call and rejects all pagination input fields (server returns Internal Server Error on page/cursor/offset/limit/etc). limit (int, optional, default=10) — RESERVED for same reason.", "operationId": "attractionsReviews", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "product_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Product ID (e.g. 'PRjYfiTKUhFz')" }, "description": "Product ID (e.g. 'PRjYfiTKUhFz')" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "description": "Reserved — Booking caps at 10/call", "default": 0 }, "description": "Reserved — Booking caps at 10/call" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "description": "Reserved — Booking caps at 10/call", "default": 10 }, "description": "Reserved — Booking caps at 10/call" }, { "name": "sort_by", "in": "query", "required": false, "schema": { "enum": [ "most_relevant", "newest", "oldest", "highest_rating", "lowest_rating" ], "type": "string", "description": "most_relevant | newest | oldest | highest_rating | lowest_rating", "nullable": true }, "description": "most_relevant | newest | oldest | highest_rating | lowest_rating" } ] } }, "/api/v1/booking/attractions/search": { "get": { "tags": [ "Attractions" ], "summary": "Search attractions", "description": "Search attractions and activities by city UFI. Returns products with prices, reviews, offers, photos, filters. Get UFI from /autocomplete or /destinations endpoints. Adaptive ufi: accepts int (-1456928), numeric string, text city name ('Paris'), or full URL ('https://booking.com/attractions/fr/paris.html').", "operationId": "attractionsSearch", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "location", "in": "query", "required": true, "schema": { "type": "string", "description": "Destination (adaptive): a place name ('Paris', 'Rome'), a Booking ufi, or an attractions URL" }, "description": "Destination (adaptive): a place name ('Paris', 'Rome'), a Booking ufi, or an attractions URL" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by availability start date YYYY-MM-DD", "nullable": true }, "description": "Filter by availability start date YYYY-MM-DD" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "description": "Filter by availability end date YYYY-MM-DD", "nullable": true }, "description": "Filter by availability end date YYYY-MM-DD" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 15 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "trending", "lowest_price", "highest_weighted_rating" ], "type": "string", "description": "trending, lowest_price, highest_weighted_rating", "nullable": true }, "description": "trending, lowest_price, highest_weighted_rating" }, { "name": "filter_type", "in": "query", "required": false, "schema": { "type": "string", "description": "Type filter tagname (from filters response)", "nullable": true }, "description": "Type filter tagname (from filters response)" }, { "name": "filter_language", "in": "query", "required": false, "schema": { "type": "string", "description": "Language filter (e.g. en, es, de)", "nullable": true }, "description": "Language filter (e.g. en, es, de)" }, { "name": "filter_rating", "in": "query", "required": false, "schema": { "type": "string", "description": "Min rating (e.g. 4.5, 4, 3.5, 3)", "nullable": true }, "description": "Min rating (e.g. 4.5, 4, 3.5, 3)" }, { "name": "filter_label", "in": "query", "required": false, "schema": { "type": "string", "description": "Label filter tagname (e.g. free_cancellation)", "nullable": true }, "description": "Label filter tagname (e.g. free_cancellation)" }, { "name": "filter_time_of_day", "in": "query", "required": false, "schema": { "type": "string", "description": "Time-of-day tagname e.g. '05:00-12:00', '12:00-18:00', '18:00-05:00'", "nullable": true }, "description": "Time-of-day tagname e.g. '05:00-12:00', '12:00-18:00', '18:00-05:00'" }, { "name": "filter_destination", "in": "query", "required": false, "schema": { "type": "string", "description": "Landmark/POI tagname from filters.destinations (e.g. Eiffel Tower)", "nullable": true }, "description": "Landmark/POI tagname from filters.destinations (e.g. Eiffel Tower)" }, { "name": "filter_area", "in": "query", "required": false, "schema": { "type": "string", "description": "Sub-location tagname from filters.locations (e.g. Versailles)", "nullable": true }, "description": "Sub-location tagname from filters.locations (e.g. Versailles)" } ] } }, "/api/v1/booking/cars/locations": { "get": { "tags": [ "Cars" ], "summary": "Car rental locations", "description": "Search airports and cities for car rental pickup/dropoff.", "operationId": "carsLocations", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "default": "us" } }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "default": "us" } } ] } }, "/api/v1/booking/cars/parse": { "get": { "tags": [ "Cars" ], "summary": "Parse any cars.booking.com URL", "description": "Universal URL router. Accepts cars.booking.com search-results URLs and deal/detail URLs and returns the appropriate scraped data.", "operationId": "carsParse", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "Full cars.booking.com URL" }, "description": "Full cars.booking.com URL" } ] } }, "/api/v1/booking/cars/search": { "get": { "tags": [ "Cars" ], "summary": "Search car rentals", "description": "Search available car rentals on Booking.com. Use IATA airport codes (LAX, JFK) or lat,lng coordinates. Returns vehicles with prices, features, suppliers, and 10+ filters. PAGINATION: upstream caps at 500 matches per query (chunk-confirmed + live-verified across 15+ probe variants — see night-run-2026-05-18/booking_cars_followup/rest_recon.md). To cover metro areas with >500 listings, fan out across nearby IATAs (e.g. LA metro: LAX+BUR+LGB+SNA; NYC metro: JFK+LGA+EWR) and merge results client-side. Response includes `total_count`, `matches_returned`, `max_supported=500`, `pagination_supported=false`, and `pagination_note` when the cap is hit.", "operationId": "carsSearch", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "pickup_location", "in": "query", "required": true, "schema": { "type": "string", "description": "IATA code (LAX) or lat,lng (33.944,-118.402)" }, "description": "IATA code (LAX) or lat,lng (33.944,-118.402)" }, { "name": "pickup_date", "in": "query", "required": true, "schema": { "type": "string", "description": "Pickup datetime (YYYY-MM-DDTHH:MM:SS)" }, "description": "Pickup datetime (YYYY-MM-DDTHH:MM:SS)" }, { "name": "dropoff_date", "in": "query", "required": true, "schema": { "type": "string", "description": "Dropoff datetime (YYYY-MM-DDTHH:MM:SS)" }, "description": "Dropoff datetime (YYYY-MM-DDTHH:MM:SS)" }, { "name": "pickup_type", "in": "query", "required": false, "schema": { "type": "string", "description": "IATA, LATLONG, or PLACE_ID", "default": "IATA" }, "description": "IATA, LATLONG, or PLACE_ID" }, { "name": "dropoff_location", "in": "query", "required": false, "schema": { "type": "string", "description": "Dropoff location (defaults to pickup)", "nullable": true }, "description": "Dropoff location (defaults to pickup)" }, { "name": "dropoff_type", "in": "query", "required": false, "schema": { "type": "string", "description": "Dropoff location type", "nullable": true }, "description": "Dropoff location type" }, { "name": "drivers_age", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 99, "minimum": 18, "default": 30 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "default": "USD" } }, { "name": "transmission", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "AUTOMATIC", "MANUAL" ], "type": "string" }, "description": "Transmission filter", "nullable": true }, "description": "Transmission filter" }, { "name": "supplier", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter: supplier display names (e.g. \"Hertz\",\"SIXT\")", "nullable": true }, "description": "Filter: supplier display names (e.g. \"Hertz\",\"SIXT\")" }, { "name": "car_category", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "small", "medium", "large", "premium", "carriers", "suvs", "convertibles", "specialcars" ], "type": "string" }, "description": "Vehicle category filter", "nullable": true }, "description": "Vehicle category filter" }, { "name": "depot_location_type", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "SHUTTLE_BUS", "IN_TERMINAL", "MEET_AND_GREET", "WALK" ], "type": "string" }, "description": "Pickup depot type filter", "nullable": true }, "description": "Pickup depot type filter" }, { "name": "fuel_type", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "PETROL", "DIESEL", "ELECTRIC", "HYBRID" ], "type": "string" }, "description": "Fuel type filter", "nullable": true }, "description": "Fuel type filter" }, { "name": "mileage", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "UNLIMITED", "LIMITED" ], "type": "string" }, "description": "Mileage policy filter", "nullable": true }, "description": "Mileage policy filter" }, { "name": "pay_when", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "PAY_NOW", "PAY_LOCAL", "PART_PAY" ], "type": "string" }, "description": "Payment timing filter", "nullable": true }, "description": "Payment timing filter" }, { "name": "seat_category", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "4", "5", "7+" ], "type": "string" }, "description": "Seat count filter", "nullable": true }, "description": "Seat count filter" }, { "name": "deposit_buckets", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "BUCKET_1", "BUCKET_2", "BUCKET_3" ], "type": "string" }, "description": "Deposit range bucket (1=<=300, 2=<=600, 3=<=900 USD)", "nullable": true }, "description": "Deposit range bucket (1=<=300, 2=<=600, 3=<=900 USD)" }, { "name": "price_per_day_buckets", "in": "query", "required": false, "schema": { "type": "array", "items": { "enum": [ "BUCKET_1", "BUCKET_2", "BUCKET_3", "BUCKET_4", "BUCKET_5" ], "type": "string" }, "description": "Price-per-day range bucket", "nullable": true }, "description": "Price-per-day range bucket" } ] } }, "/api/v1/booking/cars/supplier": { "get": { "tags": [ "Cars" ], "summary": "Supplier rating breakdown", "description": "Per-supplier rating breakdown (overall, value, friendliness, cleanliness, condition, ...). Returns review count and 9 score dimensions on 0-10 scale.", "operationId": "carsSupplier", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "description": "Supplier id (e.g. '516' for SIXT)" }, "description": "Supplier id (e.g. '516' for SIXT)" }, { "name": "location_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Location id from /search depot.location_id" }, "description": "Location id from /search depot.location_id" } ] } }, "/api/v1/booking/cars/vehicle": { "get": { "tags": [ "Cars" ], "summary": "Single vehicle detail (quote)", "description": "Fetch detail data for a specific vehicle from a prior /search result. Returns the full match + depot + supplier rating + optional supply-data and legal-notice enrichment + deal URL on cars.booking.com.", "operationId": "carsVehicle", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "description": "Vehicle id from /search" }, "description": "Vehicle id from /search" }, { "name": "pickup_location", "in": "query", "required": true, "schema": { "type": "string", "description": "IATA or lat,lng (must match /search)" }, "description": "IATA or lat,lng (must match /search)" }, { "name": "pickup_date", "in": "query", "required": true, "schema": { "type": "string", "description": "Pickup datetime" }, "description": "Pickup datetime" }, { "name": "dropoff_date", "in": "query", "required": true, "schema": { "type": "string", "description": "Dropoff datetime" }, "description": "Dropoff datetime" }, { "name": "pickup_type", "in": "query", "required": false, "schema": { "type": "string", "default": "IATA" } }, { "name": "dropoff_location", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "dropoff_type", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "drivers_age", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 99, "minimum": 18, "default": 30 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "default": "USD" } } ] } }, "/api/v1/booking/currencies": { "get": { "tags": [ "Utilities" ], "summary": "List supported currencies", "description": "Currencies accepted by Booking's `selected_currency` query param. Returns ISO 4217 code, English name, and symbol when available. Static list — cached 24h.", "operationId": "currencies", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/v1/booking/destinations": { "get": { "tags": [ "Hotels" ], "summary": "Search destinations", "description": "Autocomplete search for destinations — cities, districts, hotels, airports, landmarks. Returns coordinates and hotel counts. Use dest_id in /search for precise results.", "operationId": "destinations", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 10, "default": "en-us" } } ] } }, "/api/v1/booking/exchange-rates": { "get": { "tags": [ "Utilities" ], "summary": "Live exchange rates", "description": "Current ECB exchange rates (via api.frankfurter.app) for the requested base currency against every Booking-supported target. Refreshed daily; response cached for 1 hour.", "operationId": "exchangeRates", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "base", "in": "query", "required": false, "schema": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO 4217 base currency code (default USD)", "default": "USD" }, "description": "ISO 4217 base currency code (default USD)" } ] } }, "/api/v1/booking/flights/fly-anywhere": { "get": { "tags": [ "Flights" ], "summary": "Cheapest destinations (fly anywhere)", "description": "Get cheapest flight destinations from a city. Use city codes (NYC, LON, MIA), NOT airport codes (JFK, LHR, MIA). Returns destinations sorted by price with city info and images.", "operationId": "flightsFlyAnywhere", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "from_code", "in": "query", "required": true, "schema": { "type": "string", "description": "Origin CITY code (e.g. NYC, MIA, LON)" }, "description": "Origin CITY code (e.g. NYC, MIA, LON)" }, { "name": "depart", "in": "query", "required": true, "schema": { "type": "string", "description": "Departure date YYYY-MM-DD" }, "description": "Departure date YYYY-MM-DD" }, { "name": "return", "in": "query", "required": false, "schema": { "type": "string", "description": "Return date YYYY-MM-DD", "nullable": true }, "description": "Return date YYYY-MM-DD" }, { "name": "trip_type", "in": "query", "required": false, "schema": { "enum": [ "ROUNDTRIP", "ONEWAY" ], "type": "string", "description": "Trip type", "default": "ROUNDTRIP" }, "description": "Trip type" }, { "name": "cabin_class", "in": "query", "required": false, "schema": { "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST" ], "type": "string", "description": "Cabin class", "default": "ECONOMY" }, "description": "Cabin class" }, { "name": "adults", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9, "minimum": 1, "default": 1 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Currency code", "default": "USD" }, "description": "Currency code" } ] } }, "/api/v1/booking/flights/parse": { "get": { "tags": [ "Flights" ], "summary": "Parse any flights.booking.com URL", "description": "Auto-detect type and parse data from any flights.booking.com URL. Supports search URLs (/flights/{FROM}-{TO}/?depart=...&return=...) and discovery URLs (/fly-anywhere/?from=...&depart=...).", "operationId": "flightsParse", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "minLength": 10, "description": "Full flights.booking.com URL" }, "description": "Full flights.booking.com URL" } ] } }, "/api/v1/booking/flights/search": { "get": { "tags": [ "Flights" ], "summary": "Search flights", "description": "Search flights on Booking.com. Use IATA codes with type suffix: FRA.CITY (city), JFK.AIRPORT (airport). Returns flight offers with segments, legs, prices, baggage, and filters. Supports server-side filters (stops, airlines, maxBudget, maxDuration, includedBaggage) and client-side post-filters for time-of-day windows.", "operationId": "flightsSearch", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "from_code", "in": "query", "required": true, "schema": { "type": "string", "description": "Origin IATA code (e.g. FRA.CITY, JFK.AIRPORT)" }, "description": "Origin IATA code (e.g. FRA.CITY, JFK.AIRPORT)" }, { "name": "to_code", "in": "query", "required": true, "schema": { "type": "string", "description": "Destination IATA code (e.g. PMI.AIRPORT, LON.CITY)" }, "description": "Destination IATA code (e.g. PMI.AIRPORT, LON.CITY)" }, { "name": "depart", "in": "query", "required": true, "schema": { "type": "string", "description": "Departure date YYYY-MM-DD" }, "description": "Departure date YYYY-MM-DD" }, { "name": "return", "in": "query", "required": false, "schema": { "type": "string", "description": "Return date YYYY-MM-DD", "nullable": true }, "description": "Return date YYYY-MM-DD" }, { "name": "adults", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 9, "minimum": 1, "default": 1 } }, { "name": "children", "in": "query", "required": false, "schema": { "type": "string", "description": "Children ages comma-separated (e.g. 5,8)", "nullable": true }, "description": "Children ages comma-separated (e.g. 5,8)" }, { "name": "cabin_class", "in": "query", "required": false, "schema": { "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "FIRST" ], "type": "string", "description": "Cabin class", "default": "ECONOMY" }, "description": "Cabin class" }, { "name": "trip_type", "in": "query", "required": false, "schema": { "enum": [ "ROUNDTRIP", "ONEWAY" ], "type": "string", "description": "Trip type", "default": "ROUNDTRIP" }, "description": "Trip type" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "BEST", "CHEAPEST", "FASTEST", "OUTBOUND_TAKE_OFF_TIME" ], "type": "string", "description": "Result ordering", "default": "BEST" }, "description": "Result ordering" }, { "name": "stops", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 2, "minimum": 0, "description": "Max stops (0=direct, 1, 2)", "nullable": true }, "description": "Max stops (0=direct, 1, 2)" }, { "name": "airlines", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Filter by airline IATA codes. Pass multiple via ?airlines=LH&airlines=AF or single comma-separated value.", "nullable": true }, "description": "Filter by airline IATA codes. Pass multiple via ?airlines=LH&airlines=AF or single comma-separated value." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Currency code (USD, EUR, GBP)", "default": "USD" }, "description": "Currency code (USD, EUR, GBP)" }, { "name": "max_budget", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Upper cap on TOTAL price in `currency` units (integer)", "nullable": true }, "description": "Upper cap on TOTAL price in `currency` units (integer)" }, { "name": "max_budget_per_adult", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Upper cap on price PER ADULT in `currency` units", "nullable": true }, "description": "Upper cap on price PER ADULT in `currency` units" }, { "name": "max_duration_hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 72, "minimum": 1, "description": "Max total journey duration (hours)", "nullable": true }, "description": "Max total journey duration (hours)" }, { "name": "max_layover_hours", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 48, "minimum": 1, "description": "Max single layover duration (hours)", "nullable": true }, "description": "Max single layover duration (hours)" }, { "name": "included_baggage", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(CABIN|CHECKIN)$", "description": "'CABIN' or 'CHECKIN' — only offers that include this baggage", "nullable": true }, "description": "'CABIN' or 'CHECKIN' — only offers that include this baggage" }, { "name": "departure_time_min", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "description": "Outbound departure local time >= HH:MM (e.g. '06:00')", "nullable": true }, "description": "Outbound departure local time >= HH:MM (e.g. '06:00')" }, { "name": "departure_time_max", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "description": "Outbound departure local time <= HH:MM (e.g. '12:00')", "nullable": true }, "description": "Outbound departure local time <= HH:MM (e.g. '12:00')" }, { "name": "arrival_time_min", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "description": "Outbound arrival local time >= HH:MM", "nullable": true }, "description": "Outbound arrival local time >= HH:MM" }, { "name": "arrival_time_max", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}:\\d{2}$", "description": "Outbound arrival local time <= HH:MM", "nullable": true }, "description": "Outbound arrival local time <= HH:MM" } ] } }, "/api/v1/booking/hotels/detail": { "get": { "tags": [ "Hotels" ], "summary": "Get hotel details", "description": "Fetch full hotel details including address, facilities, and description.", "operationId": "hotelsDetail", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "hotel", "in": "query", "required": true, "schema": { "type": "string", "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Optional ISO country override; auto-derived from a URL or name", "nullable": true }, "description": "Optional ISO country override; auto-derived from a URL or name" }, { "name": "checkin", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "checkout", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } } ] } }, "/api/v1/booking/hotels/photos": { "get": { "tags": [ "Hotels" ], "summary": "Get hotel photos", "description": "Fetch hotel photo gallery with captions and categories.", "operationId": "hotelsPhotos", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "hotel", "in": "query", "required": true, "schema": { "type": "string", "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Optional ISO country override; auto-derived from a URL or name", "nullable": true }, "description": "Optional ISO country override; auto-derived from a URL or name" } ] } }, "/api/v1/booking/hotels/prices": { "get": { "tags": [ "Hotels" ], "summary": "Get hotel room prices", "description": "Fetch available room prices and availability for a hotel.", "operationId": "hotelsPrices", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "hotel", "in": "query", "required": true, "schema": { "type": "string", "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Optional ISO country override; auto-derived from a URL or name", "nullable": true }, "description": "Optional ISO country override; auto-derived from a URL or name" }, { "name": "checkin", "in": "query", "required": false, "schema": { "type": "string", "description": "Check-in date YYYY-MM-DD (required for live rates)", "nullable": true }, "description": "Check-in date YYYY-MM-DD (required for live rates)" }, { "name": "checkout", "in": "query", "required": false, "schema": { "type": "string", "description": "Check-out date YYYY-MM-DD (required for live rates)", "nullable": true }, "description": "Check-out date YYYY-MM-DD (required for live rates)" }, { "name": "adults", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 30, "minimum": 1, "default": 2 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Currency for the returned rates (USD, EUR, GBP, ... - see /currencies)", "default": "USD" }, "description": "Currency for the returned rates (USD, EUR, GBP, ... - see /currencies)" } ] } }, "/api/v1/booking/hotels/reviews": { "get": { "tags": [ "Hotels" ], "summary": "Get hotel reviews", "description": "Fetch hotel reviews via GraphQL with full filtering. Supports customer type, score range, language, season, text search. Returns reviews + available_filters for dynamic filter UI.", "operationId": "hotelsReviews", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "hotel", "in": "query", "required": true, "schema": { "type": "string", "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, "description": "Adaptive hotel identifier: a Booking.com hotel URL, an exact slug, or a hotel name" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Optional ISO country override; auto-derived from a URL or name", "nullable": true }, "description": "Optional ISO country override; auto-derived from a URL or name" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "description": "Sort: most_relevant, f_recent_desc, f_recent_asc, f_score_desc, f_score_asc", "default": "most_relevant" }, "description": "Sort: most_relevant, f_recent_desc, f_recent_asc, f_score_desc, f_score_asc" }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 25, "minimum": 1, "default": 10 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "customer_type", "in": "query", "required": false, "schema": { "type": "string", "description": "FAMILIES, COUPLES, SOLO_TRAVELLERS, GROUPS", "nullable": true }, "description": "FAMILIES, COUPLES, SOLO_TRAVELLERS, GROUPS" }, { "name": "score_range", "in": "query", "required": false, "schema": { "type": "string", "description": "REVIEW_ADJ_SUPERB, REVIEW_ADJ_GOOD, etc.", "nullable": true }, "description": "REVIEW_ADJ_SUPERB, REVIEW_ADJ_GOOD, etc." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "description": "Language code (en, de, fr, etc.)", "nullable": true }, "description": "Language code (en, de, fr, etc.)" }, { "name": "time_of_year", "in": "query", "required": false, "schema": { "type": "string", "description": "Season: _03_05, _06_08, _09_11, _12_02", "nullable": true }, "description": "Season: _03_05, _06_08, _09_11, _12_02" }, { "name": "text", "in": "query", "required": false, "schema": { "type": "string", "description": "Search text within reviews", "nullable": true }, "description": "Search text within reviews" } ] } }, "/api/v1/booking/hotels/search": { "get": { "tags": [ "Hotels" ], "summary": "Search hotels", "description": "Search Booking.com hotels by destination, dates and filters. The `location` param is adaptive - pass a place name ('Paris'), a Booking dest_id, or a Booking.com search URL.", "operationId": "hotelsSearch", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "location", "in": "query", "required": true, "schema": { "type": "string", "description": "Destination (adaptive): a place name ('Paris', 'Manhattan'), a Booking dest_id, or a Booking.com search URL" }, "description": "Destination (adaptive): a place name ('Paris', 'Manhattan'), a Booking dest_id, or a Booking.com search URL" }, { "name": "location_type", "in": "query", "required": false, "schema": { "type": "string", "description": "Optional location-type hint: city, district, region, landmark, airport, hotel", "nullable": true }, "description": "Optional location-type hint: city, district, region, landmark, airport, hotel" }, { "name": "checkin", "in": "query", "required": false, "schema": { "type": "string", "description": "Check-in date YYYY-MM-DD", "nullable": true }, "description": "Check-in date YYYY-MM-DD" }, { "name": "checkout", "in": "query", "required": false, "schema": { "type": "string", "description": "Check-out date YYYY-MM-DD", "nullable": true }, "description": "Check-out date YYYY-MM-DD" }, { "name": "adults", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 30, "minimum": 1, "default": 2 } }, { "name": "children", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10, "minimum": 0, "default": 0 } }, { "name": "rooms", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 30, "minimum": 1, "default": 1 } }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "popularity", "price", "price_low", "review_score", "review_and_price", "stars", "stars_asc", "stars_and_price", "distance" ], "type": "string", "description": "Result ordering: popularity (default), price / price_low (cheapest), review_score (top reviewed), review_and_price, stars (5-star first), stars_asc, stars_and_price, distance.", "nullable": true }, "description": "Result ordering: popularity (default), price / price_low (cheapest), review_score (top reviewed), review_and_price, stars (5-star first), stars_asc, stars_and_price, distance." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 25 } }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "Currency code (USD, EUR, GBP, ...)", "default": "USD" }, "description": "Currency code (USD, EUR, GBP, ...)" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 10, "description": "Language code (en-us, de, fr, ...)", "default": "en-us" }, "description": "Language code (en-us, de, fr, ...)" }, { "name": "price_min", "in": "query", "required": false, "schema": { "type": "number", "description": "Min price per night", "nullable": true }, "description": "Min price per night" }, { "name": "price_max", "in": "query", "required": false, "schema": { "type": "number", "description": "Max price per night", "nullable": true }, "description": "Max price per night" }, { "name": "min_review_score", "in": "query", "required": false, "schema": { "type": "number", "maximum": 10.0, "minimum": 1.0, "description": "Minimum guest review score (1-10)", "nullable": true }, "description": "Minimum guest review score (1-10)" }, { "name": "stars", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Star rating(s) 1-5; comma (stars=4,5) or repeated (stars=4&stars=5)", "nullable": true }, "description": "Star rating(s) 1-5; comma (stars=4,5) or repeated (stars=4&stars=5)" }, { "name": "property_type", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" }, "description": "Property-type id(s) (ht_id from the SERP); comma-separated or repeated", "nullable": true }, "description": "Property-type id(s) (ht_id from the SERP); comma-separated or repeated" }, { "name": "free_cancellation", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only properties with free cancellation", "nullable": true }, "description": "Only properties with free cancellation" }, { "name": "max_distance_km", "in": "query", "required": false, "schema": { "type": "number", "maximum": 50.0, "minimum": 0.1, "description": "Max distance from destination center (km)", "nullable": true }, "description": "Max distance from destination center (km)" }, { "name": "meals", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "all_inclusive", "breakfast", "half_board" ] }, "description": "Meal plans: breakfast, half_board, all_inclusive; comma-separated or repeated", "nullable": true }, "description": "Meal plans: breakfast, half_board, all_inclusive; comma-separated or repeated" }, { "name": "facilities", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "airport_shuttle", "ev_charging", "fitness_center", "free_wifi", "front_desk_24h", "hot_tub", "non_smoking_rooms", "parking", "restaurant", "room_service", "spa", "swimming_pool", "wheelchair_accessible" ] }, "description": "Property facilities (swimming_pool, free_wifi, spa, ...); comma-separated or repeated", "nullable": true }, "description": "Property facilities (swimming_pool, free_wifi, spa, ...); comma-separated or repeated" }, { "name": "room_facilities", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "air_conditioning", "balcony", "bathtub", "fireplace", "flat_screen_tv", "kitchen", "kitchenette", "lake_view", "mountain_view", "private_bathroom", "private_pool", "refrigerator", "sauna", "shower", "spa_tub", "terrace", "view", "washing_machine" ] }, "description": "Room amenities (air_conditioning, balcony, kitchen, ...); comma-separated or repeated", "nullable": true }, "description": "Room amenities (air_conditioning, balcony, kitchen, ...); comma-separated or repeated" }, { "name": "bed_preference", "in": "query", "required": false, "schema": { "enum": [ "twin", "double" ], "type": "string", "description": "Bed type: twin or double", "nullable": true }, "description": "Bed type: twin or double" }, { "name": "bedrooms", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 5, "minimum": 1, "description": "Minimum bedrooms (entire homes)", "nullable": true }, "description": "Minimum bedrooms (entire homes)" }, { "name": "bathrooms", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 6, "minimum": 1, "description": "Minimum bathrooms", "nullable": true }, "description": "Minimum bathrooms" }, { "name": "travel_flags", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "adults_only", "lgbtq_friendly", "pet_friendly" ] }, "description": "pet_friendly, adults_only, lgbtq_friendly; comma-separated or repeated", "nullable": true }, "description": "pet_friendly, adults_only, lgbtq_friendly; comma-separated or repeated" }, { "name": "accessible", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "auditory_guidance", "bathroom_emergency_cord", "braille", "lowered_sink", "raised_toilet", "tactile_signs", "toilet_grab_rails" ] }, "description": "Property accessibility features; comma-separated or repeated", "nullable": true }, "description": "Property accessibility features; comma-separated or repeated" }, { "name": "accessible_room", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "adapted_bath", "elevator_access", "emergency_cord", "ground_floor", "lower_sink", "raised_toilet", "roll_in_shower", "shower_chair", "toilet_grab_rails", "walk_in_shower", "wheelchair_accessible" ] }, "description": "Room accessibility features; comma-separated or repeated", "nullable": true }, "description": "Room accessibility features; comma-separated or repeated" }, { "name": "sustainable", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Only sustainability-certified properties", "nullable": true }, "description": "Only sustainability-certified properties" }, { "name": "rated_high", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Highly rated for breakfast", "nullable": true }, "description": "Highly rated for breakfast" }, { "name": "online_payment", "in": "query", "required": false, "schema": { "type": "boolean", "description": "Accepts online payments", "nullable": true }, "description": "Accepts online payments" } ] } }, "/api/v1/booking/languages": { "get": { "tags": [ "Utilities" ], "summary": "List supported languages", "description": "Languages Booking renders pages in via the `lang` / `selected_language` query param. Returns ISO 639-1 (or composite like en-gb / pt-br) plus native name. Static list — cached 24h.", "operationId": "languages", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/api/v1/booking/parse": { "get": { "tags": [ "Utilities" ], "summary": "Parse any Booking.com URL", "description": "Auto-detect page type and parse data from any Booking.com URL. Supports hotel detail pages (/hotel/{country}/{slug}) and search results (/searchresults?ss=...).", "operationId": "parse", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "minLength": 10, "description": "Full Booking.com URL to parse" }, "description": "Full Booking.com URL to parse" } ] } }, "/api/v1/booking/taxi/autocomplete": { "get": { "tags": [ "Taxi" ], "summary": "Taxi location autocomplete", "description": "Search airports, hotels, and addresses for taxi pickup/dropoff. Returns Google Place IDs for use in /search endpoint. The same endpoint also powers adaptive pickup/dropoff resolution in /search and /parse.", "operationId": "taxiAutocomplete", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Free-text search (place name, airport name/IATA, hotel)" }, "description": "Free-text search (place name, airport name/IATA, hotel)" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 5, "description": "ISO language code", "default": "en" }, "description": "ISO language code" } ] } }, "/api/v1/booking/taxi/parse": { "get": { "tags": [ "Taxi" ], "summary": "Parse any taxis.booking.com URL (FLAG-2)", "description": "Universal URL router. Accepts taxis.booking.com search URLs with pickup/dropoff Place IDs and returns search results.\n\nSupported URL shapes:\n - `https://taxis.booking.com/search?pickupPlaceId=…&dropoffPlaceId=…&pickupDateTime=…`\n - `https://taxis.booking.com/search?pickup=…&dropoff=…&dateTime=…`\n\nRejected with 400 (auth required, ToS-grey):\n - `https://taxis.booking.com/bookingDetails//?…` — post-booking confirmation pages require Booking-account context", "operationId": "taxiParse", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "Full taxis.booking.com URL" }, "description": "Full taxis.booking.com URL" } ] } }, "/api/v1/booking/taxi/search": { "get": { "tags": [ "Taxi" ], "summary": "Search taxi/transfer rates", "description": "Get airport taxi and transfer pricing between two locations.\n\nADAPTIVE pickup/dropoff (FLAG-1): accepts Google Place IDs (`ChIJ…`), IATA airport codes (`LAX`), full taxis.booking.com URLs, or plain text (`Heathrow Airport`) — text auto-resolves via `/autocomplete` first result.\n\nPOST-FILTERS (FLAG-6): `max_price`, `vehicle_type`, `supplier_id` are applied client-side after upstream returns all rates (Booking MFE does not accept these as input params — still costs 1 upstream call regardless).\n\nSHARED_SHUTTLE NOTE (FLAG-5): current upstream returns only `vehicle_type=CAR` in production. `frequency_minutes` is schema-preserved (forward-compatible if Booking resumes shuttle aggregation) but 0% fill-rate at present — verified 2026-05-18 across 4 high-shuttle markets (LHR→Paddington, LAX→Disneyland, JFK→Times Sq, MCO→Disney World).", "operationId": "taxiSearch", "responses": { "200": { "description": "Successful response. Envelope: { success, data, error }.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "parameters": [ { "name": "pickup", "in": "query", "required": true, "schema": { "type": "string", "description": "Pickup location — Google Place ID (`ChIJ…`), IATA airport code (`LAX`/`JFK`/`LHR`), full taxis.booking.com URL, or plain text (`Heathrow Airport`). Text auto-resolves via autocomplete." }, "description": "Pickup location — Google Place ID (`ChIJ…`), IATA airport code (`LAX`/`JFK`/`LHR`), full taxis.booking.com URL, or plain text (`Heathrow Airport`). Text auto-resolves via autocomplete." }, { "name": "dropoff", "in": "query", "required": true, "schema": { "type": "string", "description": "Dropoff location — same adaptive formats as `pickup`." }, "description": "Dropoff location — same adaptive formats as `pickup`." }, { "name": "pickup_type", "in": "query", "required": false, "schema": { "enum": [ "airport", "hotel", "train_station", "underground_railway_station", "convention_center", "lodging", "establishment", "address", "landmark", "point_of_interest" ], "type": "string", "description": "Pickup location type. Auto-detected from autocomplete result when pickup is text/IATA. Manual override accepts: airport, hotel, train_station, underground_railway_station, convention_center, lodging, establishment, address, landmark, point_of_interest.", "default": "airport" }, "description": "Pickup location type. Auto-detected from autocomplete result when pickup is text/IATA. Manual override accepts: airport, hotel, train_station, underground_railway_station, convention_center, lodging, establishment, address, landmark, point_of_interest." }, { "name": "dropoff_type", "in": "query", "required": false, "schema": { "enum": [ "airport", "hotel", "train_station", "underground_railway_station", "convention_center", "lodging", "establishment", "address", "landmark", "point_of_interest" ], "type": "string", "description": "Dropoff location type — same enum as `pickup_type`.", "default": "establishment" }, "description": "Dropoff location type — same enum as `pickup_type`." }, { "name": "pickup_datetime", "in": "query", "required": false, "schema": { "type": "string", "description": "Pickup datetime YYYY-MM-DDTHH:MM:SS", "nullable": true }, "description": "Pickup datetime YYYY-MM-DDTHH:MM:SS" }, { "name": "passengers", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 16, "minimum": 1, "default": 2 } }, { "name": "currency", "in": "query", "required": false, "schema": { "enum": [ "USD", "EUR", "GBP", "JPY", "AUD", "CAD", "CHF", "CNY", "INR", "BRL", "RUB", "MXN", "ZAR", "SGD", "HKD", "NZD", "SEK", "NOK", "DKK", "PLN", "AED", "KRW", "TRY", "ILS", "THB", "MYR", "CZK", "HUF" ], "type": "string", "description": "ISO currency code. Validated against Booking-supported list (28 codes). Invalid values now return 422 instead of 502.", "default": "USD" }, "description": "ISO currency code. Validated against Booking-supported list (28 codes). Invalid values now return 422 instead of 502." }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "description": "Post-filter — drop rates priced above this value. Applied client-side AFTER upstream returns; same upstream cost. Currency follows the `currency` param.", "nullable": true }, "description": "Post-filter — drop rates priced above this value. Applied client-side AFTER upstream returns; same upstream cost. Currency follows the `currency` param." }, { "name": "vehicle_type", "in": "query", "required": false, "schema": { "type": "string", "description": "Post-filter — restrict to a specific upstream vehicle type. Current production: only `CAR`. Future: `SHARED_SHUTTLE`/`BUS`. Case-insensitive match.", "nullable": true }, "description": "Post-filter — restrict to a specific upstream vehicle type. Current production: only `CAR`. Future: `SHARED_SHUTTLE`/`BUS`. Case-insensitive match." }, { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "integer", "description": "Post-filter — restrict to a specific supplier numeric id (`supplier_id` field from rate object). Single-value match.", "nullable": true }, "description": "Post-filter — restrict to a specific supplier numeric id (`supplier_id` field from rate object). Single-value match." } ] } } } }