{
"openapi": "3.0.1",
"info": {
"title": "Google Hotels Scraper",
"description": "Scrape Google Hotels by city and dates: hotels with nightly and total price, taxes, rating, review count, star class, amenities, coordinates, photos and booking link, plus per-site offers and guest reviews. Export data, run via API, schedule runs, or integrate with AI workflows.",
"version": "0.1",
"x-build-id": "vWGTw4g1zeh9OcdxG"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/lergassy~google-hotels-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-lergassy-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/lergassy~google-hotels-scraper/runs": {
"post": {
"operationId": "runs-sync-lergassy-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/lergassy~google-hotels-scraper/run-sync": {
"post": {
"operationId": "run-sync-lergassy-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": "📍 Where to search",
"type": "array",
"description": "One place per line, the way you would type it into Google Hotels: a city (Lisbon), a neighbourhood (Shibuya, Tokyo), a region or a landmark (hotels near Eiffel Tower). Each place is searched separately.",
"items": {
"type": "string"
}
},
"checkIn": {
"title": "📅 Check-in date",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string",
"description": "Format YYYY-MM-DD. Leave empty and the Actor searches a stay 30 days from today, so a saved task never runs on a date that has passed."
},
"checkOut": {
"title": "📅 Check-out date",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string",
"description": "Format YYYY-MM-DD. Leave empty for a two-night stay. Prices are the total for the whole stay and the average per night."
},
"adults": {
"title": "👥 Adults",
"minimum": 1,
"maximum": 8,
"type": "integer",
"description": "Number of adult guests in one room, 1–8. Google prices the room for this many people.",
"default": 2
},
"maxHotelsPerLocation": {
"title": "💯 Hotels per place",
"minimum": 1,
"maximum": 500,
"type": "integer",
"description": "Google shows 20 hotels per page and stops there. This Actor keeps going through sort orders, star classes and price bands and de-duplicates by hotel, so it can collect well over a hundred hotels for one city. Set how many you want per place.",
"default": 40
},
"currency": {
"title": "💱 Currency",
"type": "string",
"description": "Three-letter code for every price in the output: USD, EUR, GBP, IDR …",
"default": "USD"
},
"sortBy": {
"title": "Sort order",
"enum": [
"relevance",
"lowest_price",
"highest_rating",
"most_reviewed"
],
"type": "string",
"description": "Which of Google's orders to read first. The deep search visits the other orders anyway; this one decides the first page and the searchRank numbering.",
"default": "relevance"
},
"hotelClass": {
"title": "⭐ Star class",
"type": "array",
"description": "Keep only these hotel classes, e.g. 4 and 5. Unrated properties are dropped when this is set.",
"items": {
"type": "string"
}
},
"minRating": {
"title": "Minimum guest rating",
"enum": [
"",
"3.5",
"4",
"4.5"
],
"type": "string",
"description": "Drop hotels rated below this, on Google's 5-point scale. Hotels without a rating are dropped too."
},
"maxPricePerNight": {
"title": "Maximum price per night",
"minimum": 1,
"type": "integer",
"description": "In the output currency. Hotels whose average nightly price is above this are not returned."
},
"poolOnly": {
"title": "Pool required",
"type": "boolean",
"description": "Only hotels with a pool.",
"default": false
},
"includeOffers": {
"title": "🏷️ Add-on: read each hotel's page for per-site offers and reviews ($)",
"type": "boolean",
"description": "For each hotel, also open its Google Hotels page and return every booking site with its price and deep link (Booking.com, Expedia, Agoda, the hotel's own site …), the full amenity list, the full address and phone, and review scores per source. One extra request per hotel, charged as a hotel page read. The offers on that page are for the stay Google shows by default (about two weeks out) — the searched dates' price is in pricePerNight.",
"default": false
},
"maxOfferLookups": {
"title": "Hotel pages to read per run",
"minimum": 0,
"maximum": 500,
"type": "integer",
"description": "Cap on the add-on above, so a wide search does not open every page.",
"default": 20
},
"includeReviews": {
"title": "💬 Guest reviews",
"type": "boolean",
"description": "Include the reviews Google shows on the hotel page (text, rating, date, source such as Tripadvisor or Trip.com). Needs the hotel page, so it works together with the add-on above or with hotel URLs.",
"default": false
},
"maxReviews": {
"title": "Reviews per hotel",
"minimum": 1,
"maximum": 50,
"type": "integer",
"description": "Up to what Google renders on the page — typically 10 to 20.",
"default": 10
},
"hotelUrls": {
"title": "🔗 Hotel pages by URL",
"type": "array",
"description": "Google Hotels page URLs (https://www.google.com/travel/hotels/entity/…) or entity ids from an earlier run. Each becomes one row with offers, reviews and the full amenity list — no search needed.",
"items": {
"type": "string"
}
},
"language": {
"title": "Language",
"type": "string",
"description": "Two-letter code for names, descriptions and amenity labels, e.g. en, de, es.",
"default": "en"
},
"market": {
"title": "Point of sale (country)",
"type": "string",
"description": "Two-letter country code Google prices for, e.g. US, GB, DE. Sellers and rates differ per market.",
"default": "us"
},
"proxyConfiguration": {
"title": "Proxy configuration",
"type": "object",
"description": "Google answers this Actor's requests from ordinary datacenter IPs; the default Apify proxy is enough. Switch to residential only if a run reports consent pages or empty answers.",
"default": {
"useApifyProxy": true
}
},
"maxRequestRetries": {
"title": "Retries per request",
"minimum": 1,
"maximum": 10,
"type": "integer",
"description": "Each retry uses a new IP.",
"default": 3
}
}
},
"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
}
}
},
"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
}
}
}
}
}
}
}
}
}
}