{ "openapi": "3.0.1", "info": { "title": "Google Hotels Scraper: Prices by Date & Site", "description": "Google Hotels prices for any city, hotel and dates: rates from every booking site with links, taxes, ratings, amenities and photos, plus price calendars and changes-only price monitoring. Hotel price comparison from $3 per 1,000 hotels; compact JSON for AI agents.", "version": "0.1", "x-build-id": "TG564AndP56M0qmL2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleanpull~google-hotels-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleanpull-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/cleanpull~google-hotels-scraper/runs": { "post": { "operationId": "runs-sync-cleanpull-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/cleanpull~google-hotels-scraper/run-sync": { "post": { "operationId": "run-sync-cleanpull-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": { "locations": { "title": "Locations", "type": "array", "description": "Cities, neighbourhoods, landmarks or regions, one per line. Each becomes the Google Hotels search \"hotels in \" (or \"vacation rentals in \"). A line that already says what to find, such as \"boutique hotels near the Eiffel Tower\", is searched as written.", "items": { "type": "string" } }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Optional. Free-form Google Hotels searches, exactly as you would type them in Google, for example \"hotels with pool near Disneyland Paris\".", "items": { "type": "string" } }, "hotels": { "title": "Hotels by name", "type": "array", "description": "Optional. Specific hotels to price, one per line, for example \"Avenida Palace Lisbon\". Adding the city helps Google find the right one. Use this to watch a competitive set of hotels.", "items": { "type": "string" } }, "startUrls": { "title": "Google Hotels URLs", "type": "array", "description": "Optional. Google Hotels hotel pages (google.com/travel/hotels/entity/...) or search pages (google.com/travel/search?q=...). Hotel pages return that hotel; search pages run their query.", "items": { "type": "string" } }, "propertyType": { "title": "Property type", "enum": [ "hotels", "vacation-rentals" ], "type": "string", "description": "Search hotels or vacation rentals (apartments, houses).", "default": "hotels" }, "checkInDate": { "title": "Check-in date", "pattern": "^\\s*(\\d{4}-\\d{2}-\\d{2}|([tT][oO][dD][aA][yY])?\\s*\\+\\s*\\d{1,3}(\\s*[dD]([aA][yY][sS]?)?)?|[tT][oO][dD][aA][yY])?\\s*$", "type": "string", "description": "YYYY-MM-DD, or +N for N days after the day the run starts (for example +30). Use +N in scheduled runs so they keep looking the same distance ahead. Dates already past are skipped with a warning.", "default": "+14" }, "checkOutDate": { "title": "Check-out date", "pattern": "^\\s*(\\d{4}-\\d{2}-\\d{2}|([tT][oO][dD][aA][yY])?\\s*\\+\\s*\\d{1,3}(\\s*[dD]([aA][yY][sS]?)?)?|[tT][oO][dD][aA][yY])?\\s*$", "type": "string", "description": "Optional. YYYY-MM-DD or +N. Sets the length of stay; ignored when Nights is set. Without either, stays are 1 night." }, "nights": { "title": "Nights", "type": "array", "description": "Optional. One or more lengths of stay, for example [1, 3, 7]. Each check-in date is priced for each length." }, "checkInDates": { "title": "More check-in dates", "type": "array", "description": "Optional. Extra check-in dates (YYYY-MM-DD or +N), each priced like the first.", "items": { "type": "string" } }, "checkInDateTo": { "title": "Check-in dates up to", "pattern": "^\\s*(\\d{4}-\\d{2}-\\d{2}|([tT][oO][dD][aA][yY])?\\s*\\+\\s*\\d{1,3}(\\s*[dD]([aA][yY][sS]?)?)?|[tT][oO][dD][aA][yY])?\\s*$", "type": "string", "description": "Optional. Price every check-in date from Check-in date up to this date (YYYY-MM-DD or +N), every Date step days: a price calendar." }, "dateStep": { "title": "Date step (days)", "minimum": 1, "maximum": 30, "type": "integer", "description": "Days between check-in dates in a date range.", "default": 1 }, "adults": { "title": "Adults", "minimum": 1, "maximum": 30, "type": "integer", "description": "Adult guests.", "default": 2 }, "childrenAges": { "title": "Children (ages)", "type": "array", "description": "Ages of child guests, for example [4, 9]. Prices change with the number and ages of children.", "default": [] }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "lowest-price", "highest-rating", "most-reviewed" ], "type": "string", "description": "Google's sort order. With a Max results limit, this decides which hotels you get.", "default": "relevance" }, "minPrice": { "title": "Minimum price per night", "minimum": 0, "type": "integer", "description": "Optional. In the chosen currency." }, "maxPrice": { "title": "Maximum price per night", "minimum": 0, "type": "integer", "description": "Optional. In the chosen currency." }, "minRating": { "title": "Minimum guest rating", "enum": [ "3.5", "4", "4.5" ], "type": "string", "description": "Optional. Only hotels rated at least this on Google." }, "hotelClass": { "title": "Minimum star class", "minimum": 2, "maximum": 5, "type": "integer", "description": "Optional. Only hotels with at least this many stars (2 to 5)." }, "hotelClasses": { "title": "Exact star classes", "type": "array", "description": "Optional. Only these star classes, for example [3, 4]. Overrides Minimum star class." }, "amenities": { "title": "Amenities", "type": "array", "description": "Optional. Only properties with all of these amenities (the filters Google Hotels offers).", "items": { "type": "string", "enum": [ "free-wifi", "free-breakfast", "restaurant", "bar", "kid-friendly", "pet-friendly", "free-parking", "parking", "ev-charger", "room-service", "fitness-center", "spa", "pool", "indoor-pool", "outdoor-pool", "air-conditioned", "wheelchair-accessible", "beach-access", "all-inclusive" ], "enumTitles": [ "Free Wi-Fi", "Free breakfast", "Restaurant", "Bar", "Kid-friendly", "Pet-friendly", "Free parking", "Parking", "EV charger", "Room service", "Fitness center", "Spa", "Pool (any)", "Indoor pool", "Outdoor pool", "Air-conditioned", "Wheelchair accessible", "Beach access", "All-inclusive available" ] }, "default": [] }, "hotelTypes": { "title": "Hotel types", "type": "array", "description": "Optional. Only these kinds of hotel.", "items": { "type": "string", "enum": [ "hostel", "bed-and-breakfast", "boutique-hotel", "spa-hotel", "beach-hotel", "apartment-hotel", "inn", "motel", "other" ], "enumTitles": [ "Hostels", "Bed and breakfasts", "Boutique hotels", "Spa hotels", "Beach hotels", "Apartment hotels", "Inns", "Motels", "Other" ] } }, "brands": { "title": "Hotel brands", "type": "array", "description": "Optional. Brand or chain names as Google lists them for the place, for example \"Marriott Bonvoy\" (with all its brands) or \"Moxy\". Unknown names are reported in the log.", "items": { "type": "string" } }, "freeCancellation": { "title": "Free cancellation only", "type": "boolean", "description": "Only offers that can be cancelled for free.", "default": false }, "specialOffers": { "title": "Special offers only", "type": "boolean", "description": "Only hotels with a special offer or deal.", "default": false }, "maxResults": { "title": "Max results per search", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hotels per location, query and stay. The actor pages through Google (20 a page), and when Google stops paging a search (it shows a few hundred hotels at most), runs extra passes with other sort orders and price bands until it has this many or Google has no more. Sorted by lowest price, extra passes continue from the highest price seen, so results stay in price order.", "default": 20 }, "maxItems": { "title": "Max results per run", "minimum": 1, "type": "integer", "description": "Optional. Stop after this many results in total (a cost cap)." }, "includeBookingSources": { "title": "Booking sources (all sites)", "type": "boolean", "description": "Fetch each hotel's full price list: every booking site (Booking.com, Expedia, Agoda, the hotel's own site...) with nightly and total prices, taxes and booking links, and review scores by site. One extra request per hotel, billed as a detail.", "default": false }, "includeRoomRates": { "title": "Room rates", "type": "boolean", "description": "Also return room-level rates (room name, price per site, free-cancellation deadline). Comes with the same detail request as booking sources.", "default": false }, "monitorMode": { "title": "Changes only (monitoring)", "type": "boolean", "description": "Remember each run and return only what changed since the last run under the same Monitor name: price drops and rises, hotels selling out or coming back, new and removed hotels. Unchanged hotels are billed at a fraction of a result.", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Runs with the same name compare with each other. Use one name per watch list.", "default": "default" }, "changeTypes": { "title": "Changes to report", "type": "array", "description": "Which changes count. The first run reports every hotel as new.", "items": { "type": "string", "enum": [ "new", "price-drop", "price-rise", "sold-out", "back-in-stock", "removed" ], "enumTitles": [ "New in the results", "Price dropped", "Price rose", "Sold out (price disappeared)", "Back in stock (price reappeared)", "Removed from the results" ] }, "default": [ "new", "price-drop", "price-rise", "sold-out", "back-in-stock", "removed" ] }, "priceChangePercent": { "title": "Minimum price change (%)", "minimum": 0, "type": "number", "description": "Ignore price moves smaller than this percentage.", "default": 1 }, "priceChangeMinAmount": { "title": "Minimum price change (amount)", "minimum": 0, "type": "number", "description": "Ignore price moves smaller than this amount in the chosen currency.", "default": 0 }, "removedAfterRuns": { "title": "Removed after missing runs", "minimum": 1, "maximum": 30, "type": "integer", "description": "Report a hotel as removed only after it is missing from this many runs in a row (Google reshuffles results; one miss is often noise). Only searches that reached the end of Google's results count.", "default": 2 }, "currency": { "title": "Currency", "pattern": "^\\s*([A-Za-z]{3})?\\s*$", "type": "string", "description": "Three-letter currency code for prices, for example USD, EUR, GBP, JPY.", "default": "USD" }, "languageCode": { "title": "Language", "type": "string", "description": "Language for names and descriptions (Google hl), for example en, fr, de, es.", "default": "en" }, "countryCode": { "title": "Country", "type": "string", "description": "Region Google searches from (Google gl), for example us, gb, de. Prices can differ by region.", "default": "us" }, "outputFormat": { "title": "Output format", "enum": [ "nested", "flat" ], "type": "string", "description": "Nested keeps lists (booking sources, rooms, amenities) inside each hotel. Flat gives one row per hotel and booking site with plain columns, for CSV, Excel and AI agents.", "default": "nested" }, "fields": { "title": "Only these fields", "type": "array", "description": "Optional. Keep only these fields in each record, for example [\"hotelName\", \"pricePerNight\", \"bookingSources\"]. Dotted paths reach nested fields.", "items": { "type": "string" } }, "searchQuery": { "title": "Search query (single)", "type": "string", "description": "Optional. One search query; same as adding it to Search queries." }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "Timeout for each request to Google.", "default": 30 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. The actor picks proxies itself: direct first, then datacenter, then residential only if Google blocks the others. Set a proxy here to use it after the direct attempt." } } }, "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 } } } } } } } } } }