{ "openapi": "3.0.1", "info": { "title": "Hotel Rate Parity Checker — OTA Price Comparison", "description": "Rate parity check on Google Hotels by name or URL. One row per hotel and stay: every OTA and official site side by side (Booking.com, Expedia, Agoda), nightly rate, free cancellation, link; cheapest source, spread, direct booking rate, undercut by whom and how much. minSpreadPct: violations only.", "version": "1.0", "x-build-id": "dHTmKolYYoAYtpLnY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/kestrel~hotel-rate-parity/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-kestrel-hotel-rate-parity", "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/kestrel~hotel-rate-parity/runs": { "post": { "operationId": "runs-sync-kestrel-hotel-rate-parity", "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/kestrel~hotel-rate-parity/run-sync": { "post": { "operationId": "run-sync-kestrel-hotel-rate-parity", "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", "required": [ "checkIn" ], "properties": { "hotelNames": { "title": "Properties by name", "uniqueItems": true, "type": "array", "description": "Hotels by name, e.g. [\"Hyatt Regency Lisbon\", \"Altis Grand Hotel Lisbon\"]: use for \"is anyone undercutting hotel X\" when you have no Google Hotels URL. One free Google search per name; the listing is kept only when its name shares at least two words and 60% of yours, so a stranger is never billed. A name that matches nothing is a free not_found status row: retry with the name as Google spells it (a city Google omits from the name counts against it), or pass the entity_id of a row in hotels.", "default": [], "items": { "type": "string" } }, "hotels": { "title": "Properties (Google Hotels URLs or entity tokens)", "uniqueItems": true, "type": "array", "description": "Exact hotels by Google Hotels URL (https://www.google.com/travel/hotels/entity/ChkI…) or entity token, e.g. the entity_id of a row from an earlier run or from kestrel/google-hotels-prices. No search: one offers call per hotel and stay, nothing unrelated is ever billed. Use to check the SAME hotels every morning (your property and its comp set): resolve names once, then pass their entity_id values here. Names belong in hotelNames.", "items": { "type": "string" } }, "checkIn": { "title": "Check-in", "pattern": "^(\\d{4}-\\d{2}-\\d{2}|\\+?\\s*\\d+\\s*(d|days?|w|weeks?|m|months?|y|years?)|today|tomorrow)$", "type": "string", "description": "Check-in date: \"2026-11-02\" (YYYY-MM-DD), or relative to the day the run starts: \"30 days\", \"6 weeks\", \"+30d\", \"today\", \"tomorrow\". Use relative dates for a schedule (\"check parity daily\"): the input never needs editing and every run looks the same distance ahead. A past date is rejected before anything is charged. Required." }, "nights": { "title": "Nights", "minimum": 1, "maximum": 30, "type": "integer", "description": "Length of stay in nights, 1 to 30, e.g. 2 (default 1). Check-out = check-in + nights. Every source's rate in the row is for this exact stay and occupancy.", "default": 1 }, "sweepDays": { "title": "Sweep check-in over N more days", "minimum": 0, "maximum": 60, "type": "integer", "description": "0 (default) = only the stay above. N = also check the same length of stay starting on each of the next N days, e.g. 6 = 7 check-in dates per hotel, one row each. Use for \"next week\", \"the weekend\", \"a rate calendar\", \"the next 30 days\" (29). Every stay is billed as its own row, so cost × (N + 1): 5 hotels × sweepDays 6 = 35 rows = $0.35. Maximum 60.", "default": 0 }, "minSpreadPct": { "title": "Only keep spreads of at least N %", "minimum": 0, "maximum": 1000, "type": "number", "description": "0 (default) = deliver every hotel and stay. N = deliver only rows whose spread between the cheapest and dearest source is at least N %, e.g. 5: the violations-only feed. Rows under N get a free status row (status \"filtered\") and are never billed. Use for \"only parity breaches\", \"only where the gap is over 10%\". It filters on spread_pct (cheapest vs dearest source), not on undercut_pct: for \"only where an OTA undercuts the official site\" keep 0 and filter rows on undercut_by.", "default": 0 }, "adults": { "title": "Adults", "minimum": 1, "maximum": 6, "type": "integer", "description": "Adults in the room, 1 to 6, e.g. 2 (default 2). Google prices ONE room for the whole party: there is no rooms input, and above 6 adults Google returns no price at all. Rates scale with occupancy exactly as on Google, so compare like with like.", "default": 2 }, "childrenAges": { "title": "Children (ages)", "type": "array", "description": "Ages of the children in the same room, e.g. [5, 9] for two children aged 5 and 9. Empty (default) = no children. The price is for one room holding the adults plus these children.", "default": [] }, "currency": { "title": "Currency", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "type": "string", "description": "ISO 4217 code for every price in the run, e.g. \"EUR\" (default \"USD\"): USD, EUR, GBP, JPY, THB, SGD, AUD, AED… When the user names no currency, pass the hotel's own (\"EUR\" for Lisbon). Every source's rate in the row is in this one currency.", "default": "USD" }, "country": { "title": "Market", "type": "string", "description": "Google market (gl): any 2-letter country code, e.g. \"gb\", \"pt\", \"jp\" (default \"us\"). It is the country of the person booking, NOT the hotel's: keep \"us\" unless the user wants the parity picture as seen from a market. It changes which booking sites Google lists (Klook, Traveloka, Wego in Asian markets), so keep one market across a history.", "default": "us" }, "language": { "title": "Language", "type": "string", "description": "Google language (hl), e.g. \"en\", \"de\", \"ja\" (default \"en\"). Sets the language of hotel and source names where Google has a translation; hotelNames may be written in any language.", "default": "en" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Keep the default (Apify datacenter proxies): Google accepts them for these calls, residential is unnecessary.", "default": { "useApifyProxy": true } }, "sessions": { "title": "Parallel proxy sessions", "minimum": 1, "maximum": 16, "type": "integer", "description": "Parallel proxy sessions, 1 to 16, e.g. 4 (default 4); each is paced at perIp requests per second. Raise for many hotels × stays, lower if Google throttles.", "default": 4 }, "perIp": { "title": "Requests per second per IP", "minimum": 0.1, "maximum": 2, "type": "number", "description": "Requests per second per proxy session, 0.1 to 2, e.g. 0.5 (default 0.5). 0.5 is safe; raise carefully.", "default": 0.5 } } }, "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 } } } } } } } } } }