{ "openapi": "3.0.1", "info": { "title": "Google Hotels Scraper & API — Hotel Prices & Rates", "description": "Google Hotels scraper and API for hotel price comparison: prices for your dates, ratings, amenities, deals and price calendars. Full details add every booking site's price (Booking.com, Expedia, the hotel's own site…), room rates and rate parity. Search any city or paste links. No platform fees.", "version": "1.1", "x-build-id": "up5wFYbQ622jILnhL" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/aaronoptimus~google-hotels-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-aaronoptimus-google-hotels-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/aaronoptimus~google-hotels-scraper/runs": { "post": { "operationId": "runs-sync-aaronoptimus-google-hotels-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/aaronoptimus~google-hotels-scraper/run-sync": { "post": { "operationId": "run-sync-aaronoptimus-google-hotels-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchQueries": { "title": "Destinations or Google Hotels search links", "type": "array", "description": "Where to search, as you would type it on Google Hotels: a city, area or landmark (\"Austin, TX\", \"hotels near Times Square\", \"Lake Tahoe cabins\"). You can also paste a Google Hotels search link (its dates are used when you leave the dates below empty) or a hotel link (that hotel comes with full details, like under \"Specific hotels\").", "items": { "type": "string" } }, "hotels": { "title": "Specific hotels (links or names)", "type": "array", "description": "Optional. Google Hotels hotel links, Google Hotels IDs (they start with Ch), or hotel names such as \"The Plaza New York\" (the Google Hotels result whose name matches best is used; if none matches, you get an error, not a charge). Each hotel is returned with full details and every booking site's price.", "items": { "type": "string" } }, "checkInDate": { "title": "Check-in date", "type": "string", "description": "A date like 2026-11-20, or a date relative to the run like \"14 days\". Leave empty to use Google's default dates; a stay of more than one night then starts tomorrow." }, "checkOutDate": { "title": "Check-out date", "type": "string", "description": "Optional. Leave empty to stay for the number of nights below." }, "nights": { "title": "Nights", "minimum": 1, "maximum": 30, "type": "integer", "description": "Length of stay when no check-out date is set (Google Hotels shows prices for up to 30 nights).", "default": 1 }, "numberOfCheckInDates": { "title": "Price calendar: number of check-in dates", "minimum": 1, "maximum": 60, "type": "integer", "description": "Repeat every search for this many consecutive check-in dates, keeping the same length of stay. For example 30 gives you each hotel's price for every day of the next month. Without a check-in date it starts on a pasted link's dates, or tomorrow.", "default": 1 }, "adults": { "title": "Adults", "minimum": 1, "maximum": 12, "type": "integer", "description": "Number of adults. Prices depend on it.", "default": 2 }, "childrenAges": { "title": "Children's ages", "type": "array", "description": "Optional. One age (0-17) per child, e.g. 8 and 12 for two children. Up to 6 children.", "items": { "type": "string" } }, "currency": { "title": "Currency", "pattern": "^[A-Za-z]{3}$", "type": "string", "description": "3-letter currency code for all prices, e.g. USD, EUR, GBP, CAD, AUD, JPY, INR.", "default": "USD" }, "country": { "title": "Country", "type": "string", "description": "2-letter country code you search from, e.g. US, GB, DE, IN. Google adapts which booking sites it shows and whether prices include taxes; Apify Proxy IPs are taken from this country.", "default": "US" }, "language": { "title": "Language", "type": "string", "description": "Language of hotel descriptions and texts, e.g. en-US, en-GB, de, fr, es, ja.", "default": "en-US" }, "propertyType": { "title": "Property type", "enum": [ "hotels", "vacationRentals" ], "type": "string", "description": "Hotels, or vacation rentals (homes and apartments).", "default": "hotels" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "lowestPrice", "highestRating", "mostReviewed" ], "type": "string", "description": "Order of the results.", "default": "relevance" }, "minPrice": { "title": "Minimum price per night", "minimum": 0, "type": "integer", "description": "In the currency above." }, "maxPrice": { "title": "Maximum price per night", "minimum": 0, "type": "integer", "description": "In the currency above." }, "hotelClass": { "title": "Hotel class", "type": "array", "description": "Only hotels with these star ratings.", "items": { "type": "string", "enum": [ "2", "3", "4", "5" ], "enumTitles": [ "2-star", "3-star", "4-star", "5-star" ] } }, "minRating": { "title": "Minimum guest rating", "enum": [ "3.5", "4", "4.5" ], "type": "string", "description": "Only hotels rated at least this high by guests." }, "amenities": { "title": "Amenities", "type": "array", "description": "Only hotels that have all of these.", "items": { "type": "string", "enum": [ "freeWifi", "freeBreakfast", "freeParking", "parking", "pool", "indoorPool", "outdoorPool", "hotTub", "fitnessCenter", "spa", "restaurant", "bar", "roomService", "airConditioned", "petFriendly", "kidFriendly", "beachAccess", "allInclusive", "wheelchairAccessible", "evCharger" ], "enumTitles": [ "Free Wi-Fi", "Free breakfast", "Free parking", "Parking", "Pool", "Indoor pool", "Outdoor pool", "Hot tub", "Fitness center", "Spa", "Restaurant", "Bar", "Room service", "Air-conditioned", "Pet-friendly", "Kid-friendly", "Beach access", "All-inclusive", "Wheelchair accessible", "EV charger" ] } }, "brands": { "title": "Brands", "type": "array", "description": "Only hotels from these chains (all of each chain's brands, e.g. Hilton includes Hampton and DoubleTree).", "items": { "type": "string", "enum": [ "accor", "bestWestern", "choice", "extendedStayAmerica", "fourSeasons", "hilton", "hyatt", "ihg", "marriott", "omni", "radisson", "redRoof", "sonesta", "wyndham" ], "enumTitles": [ "Accor", "Best Western", "Choice Hotels", "Extended Stay America", "Four Seasons", "Hilton", "Hyatt", "IHG Hotels & Resorts", "Marriott Bonvoy", "Omni Hotels", "Radisson Hotel Group", "Red Roof", "Sonesta", "Wyndham" ] } }, "freeCancellation": { "title": "Free cancellation only", "type": "boolean", "description": "Only hotels with a free-cancellation rate.", "default": false }, "specialOffers": { "title": "Special offers only", "type": "boolean", "description": "Only hotels with a deal or special offer.", "default": false }, "ecoCertified": { "title": "Eco-certified only", "type": "boolean", "description": "Only hotels with an eco certification.", "default": false }, "maxHotelsPerSearch": { "title": "Max hotels per destination", "minimum": 1, "maximum": 1000, "type": "integer", "description": "How many hotels to return per destination (and per check-in date). Google shows about 20 per page; more hotels take more pages.", "default": 20 }, "includeDetails": { "title": "Full details and every booking site's price", "type": "boolean", "description": "Open each hotel's page: prices from every booking site with direct links, a rate-parity check (the hotel's own site against the cheapest other site), room offers, address, phone, all amenities, review breakdown and nearby places. Charged as \"Hotel with all booking sites\" instead of \"Hotel\". Specific hotels always get full details.", "default": false }, "outputFormat": { "title": "Output format", "enum": [ "items", "rows" ], "type": "string", "description": "Items: one rich JSON record per hotel (best for the API and code). Rows: flat rows with the same columns everywhere, one per hotel and booking site (best for CSV, Excel and Google Sheets).", "default": "items" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Google throttles repeated requests. Apify Proxy is recommended; sessions and IPs rotate automatically. IPs come from the Country above unless you pick a proxy country here.", "default": { "useApifyProxy": true } }, "useResidentialFallback": { "title": "Fall back to residential proxy when blocked", "type": "boolean", "description": "If Google keeps blocking the default proxy, switch to Apify residential proxy in the same country automatically. No extra cost to you.", "default": true }, "maxConcurrency": { "title": "Parallel sessions", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many requests run at the same time, each with its own session and IP. Higher is faster for big runs.", "default": 5 }, "maxRetries": { "title": "Max retries per request", "minimum": 0, "maximum": 15, "type": "integer", "description": "How many times to retry with a fresh session and IP when Google throttles a request.", "default": 6 }, "maxSecondsPerTask": { "title": "Time limit per page or hotel (seconds)", "minimum": 30, "maximum": 600, "type": "integer", "description": "Stop retrying a page or hotel after this long so one stubborn request can't stall the run. It is reported as failed and not charged.", "default": 120 }, "delayBetweenRequestsSecs": { "title": "Delay between requests (seconds)", "minimum": 0, "maximum": 30, "type": "integer", "description": "Pause between requests in each session to stay under Google's rate limits.", "default": 1 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }