{ "openapi": "3.0.1", "info": { "title": "Tripadvisor Hotel Reputation Monitor", "description": "Monitors a portfolio of hotels on Tripadvisor and returns a ranked attention queue: which property needs attention, what changed since the last run, the reviews behind it, and the team best placed to investigate. Subrating trends, response gaps, comp-set context.", "version": "1.0", "x-build-id": "auGZfUOUs9OvOTd6w" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ryanclinton~tripadvisor-hotel-reputation-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ryanclinton-tripadvisor-hotel-reputation-monitor", "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/ryanclinton~tripadvisor-hotel-reputation-monitor/runs": { "post": { "operationId": "runs-sync-ryanclinton-tripadvisor-hotel-reputation-monitor", "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/ryanclinton~tripadvisor-hotel-reputation-monitor/run-sync": { "post": { "operationId": "run-sync-ryanclinton-tripadvisor-hotel-reputation-monitor", "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": { "mode": { "title": "What do you want this run to do?", "enum": [ "monitor", "audit", "compset", "discover", "reviews" ], "type": "string", "description": "Monitor tracks a portfolio over time and returns only what changed since the last run, which is what the actor is built for. Audit runs a one-off evidence-based review of specific properties. Comp-set compares one property against named competitors and nearby candidates. Discover turns a hotel list page into property URLs you can paste into the other modes. Reviews returns a review-forward output shape for migrating an existing pipeline.", "default": "monitor" }, "propertyUrls": { "title": "Property URLs", "maxItems": 500, "type": "array", "description": "Tripadvisor hotel page URLs to monitor or audit, in the form https://www.tripadvisor.com/Hotel_Review-g60763-d1234567-Reviews-Property_Name-City.html. Properties are identified by their numeric Tripadvisor id rather than the name in the URL, so a rename or a URL change does not split a property's history in two.", "items": { "type": "string" } }, "discoveryUrls": { "title": "Hotel list pages", "maxItems": 50, "type": "array", "description": "Tripadvisor hotel list page URLs for a city or area, in the form https://www.tripadvisor.com/Hotels-g60763-New_York_City_New_York-Hotels.html. Every property found on the page is added to the run, up to your property limit. Use this when you want a location rather than a hand-listed set of properties.", "items": { "type": "string" } }, "watchlistName": { "title": "Watchlist name", "type": "string", "description": "A label for this portfolio, shown on every record and every alert. History is stored against a stable internal id derived from the properties themselves, so renaming a watchlist never resets its history and two watchlists with the same name never collide." }, "focalPropertyUrl": { "title": "Focal property", "type": "string", "description": "Comp-set mode: the Tripadvisor hotel page URL of the property everything else is compared against." }, "competitorUrls": { "title": "Competitor property URLs", "maxItems": 30, "type": "array", "description": "Tripadvisor hotel page URLs of the competitors you want in the comparison. A competitor you list here is pinned: it stays in the comp set across runs even when the automatic selection would drop it, so the comparison does not reshuffle underneath you.", "items": { "type": "string" } }, "includeGeoCompSetCandidates": { "title": "Suggest nearby comparable properties", "type": "boolean", "description": "Also consider the other properties collected in this run as comp-set candidates, scored on how comparable they actually are. Suggestions are returned separately from confirmed comparables so nothing is silently added to your comparison.", "default": false }, "compSetRadiusKm": { "title": "Comparison radius (km)", "minimum": 1, "maximum": 50, "type": "integer", "description": "How far from the focal property a candidate can be and still be considered comparable. Distance is one input among several, never the deciding one.", "default": 3 }, "maxCompSetCandidates": { "title": "Maximum comparison candidates", "minimum": 0, "maximum": 30, "type": "integer", "description": "Upper limit on how many nearby properties are scored for comparability in a single run.", "default": 8 }, "collectionPolicy": { "title": "How much to collect per property", "enum": [ "incremental", "recent_window", "target_sample", "diagnostic", "metadata_only" ], "type": "string", "description": "Leave this empty and the mode picks for you: monitor collects only what is new since the last run, audit collects a diagnostic sample, comp-set covers the recent window, discover collects details only, and reviews collects to a target sample. Set it explicitly when you want to override that." }, "recentWindowDays": { "title": "Recent window (days)", "minimum": 7, "maximum": 365, "type": "integer", "description": "The window that counts as recent for change detection, theme shares and the freshness contract. Shorter windows react faster and carry thinner samples, and the confidence reported with every signal reflects that.", "default": 90 }, "baselineWindowDays": { "title": "Baseline window (days)", "minimum": 30, "maximum": 730, "type": "integer", "description": "How far back the comparison baseline is allowed to reach when previous observations exist.", "default": 365 }, "targetReviewSample": { "title": "Target reviews per property", "minimum": 0, "maximum": 500, "type": "integer", "description": "How many reviews a full collection aims to gather per property. Leave empty to let the mode choose. Collection also stops on its other conditions, so the number actually collected can be lower and the reason is reported per property." }, "maxStalenessDaysOverride": { "title": "Maximum days between full collections", "minimum": 1, "maximum": 180, "type": "integer", "description": "Every property is fully collected at least this often even when nothing on its summary appears to have moved, because a property can deteriorate while its rounded rating holds. Leave empty and the interval is set from each property's own observed review velocity." }, "controlSampleShare": { "title": "Control sample share", "minimum": 0, "maximum": 0.5, "type": "number", "description": "Share of properties that receive a full collection each run regardless of whether anything appeared to change, as a check on the selection itself. Set to 0 to switch the control sample off.", "default": 0.05 }, "analysisLanguage": { "title": "Language for review text analysis", "enum": [ "en" ], "type": "string", "description": "Review text analysis is supported for English in this version. Reviews in other languages still count towards ratings, subratings, volume and response metrics, and the excluded share is reported per property and lowers the confidence attached to every signal.", "default": "en" }, "translationPreference": { "title": "Review language presentation", "enum": [ "sourceDisplayed", "originalOnly" ], "type": "string", "description": "Whether to work with reviews as the page presents them, or to prefer the original text where both are shown. This is recorded on every property so a difference between two runs is explainable rather than mysterious.", "default": "sourceDisplayed" }, "includeReviewRecords": { "title": "Include individual review rows", "type": "boolean", "description": "Add one row per collected review alongside the property and decision rows. Leave empty and the mode decides: the review-forward migration mode includes them, the decision modes do not. Turn it on in any mode when you want the underlying rows in your warehouse." }, "includeReviewerDisplayName": { "title": "Include reviewer display names", "type": "boolean", "description": "Off by default. When on, review rows carry the display name shown on the review. No other reviewer detail is ever collected or returned: no profile links, no contribution counts and no home location, whatever this is set to.", "default": false }, "propertyMetadata": { "title": "Your own property metadata", "type": "array", "description": "Optional list of objects that attach your own identifiers to each property, for example [{\"propertyId\":\"1234567\",\"internalPropertyId\":\"NYC-01\",\"region\":\"Northeast\",\"owner\":\"Jane Doe\",\"brand\":\"Riverside\"}]. Match on propertyId or url. These values are carried on every record and every alert in their own namespace, so the output joins to your operating structure without a lookup and never overwrites anything read from the source." }, "watchlistId": { "title": "Watchlist id", "type": "string", "description": "Advanced. Pin the internal id that history is stored against. Leave empty and it is resolved automatically from the properties, which is what keeps history intact when you rename a watchlist or add and remove properties." }, "resetScope": { "title": "Reset stored history", "enum": [ "none", "propertyBaselines", "signalHistory", "compSet", "reviewBoundary", "entireWatchlist" ], "type": "string", "description": "Deliberately discard part of the stored history before this run. What was reset is reported in the run summary, because a silent history wipe is indistinguishable from a monitoring fault. Leave on None unless you specifically want to start a baseline again.", "default": "none" }, "confirmReset": { "title": "Confirm reset", "type": "boolean", "description": "Required for a reset to actually happen. Discarded history cannot be rebuilt by re-running, so a reset scope on its own does nothing: leave this off and the run proceeds normally with your history intact, and the run summary records that an unconfirmed reset was requested. Switch it on only when you intend to discard the history you selected above.", "default": false }, "maxProperties": { "title": "Maximum properties", "minimum": 1, "maximum": 500, "type": "integer", "description": "Upper limit on properties handled in one run. Anything above the limit is still returned, marked as deferred with the reason and when it becomes eligible again, so a portfolio never silently loses members." }, "maxHydratedProperties": { "title": "Maximum properties with review collection", "minimum": 0, "maximum": 500, "type": "integer", "description": "Upper limit on how many properties receive the expensive review collection in one run. Leave empty and the mode chooses. Properties are selected by what actually changed, what has an open high-priority signal, and what is due for its periodic full collection." }, "maxRunMinutes": { "title": "Maximum run minutes", "minimum": 3, "maximum": 240, "type": "integer", "description": "Wall-clock budget for the run. On reaching it the run stops collecting, emits everything already produced, and leaves untouched properties on their previous baselines.", "default": 60 }, "maxReviewInteractionsPerProperty": { "title": "Maximum collection steps per property", "minimum": 0, "maximum": 60, "type": "integer", "description": "Upper bound on how far collection will go on a single property. Collection is adaptive and usually stops well before this on its own conditions, which are reported per property.", "default": 14 }, "startUrls": { "title": "Start URLs (compatibility)", "maxItems": 500, "type": "array", "description": "Accepted for migrating an existing pipeline. Property URLs and hotel list pages are separated by URL kind rather than assumed, and every alias applied is reported back in the run summary so the migration is auditable.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxReviewsPerProperty": { "title": "Maximum reviews per property (compatibility)", "minimum": 0, "maximum": 500, "type": "integer", "description": "Accepted for migrating an existing pipeline. Applied as the per-property collection target. Collection also stops on its other conditions, so the number returned can be lower and the reason is reported per property." }, "language": { "title": "Language (compatibility)", "type": "string", "description": "Accepted for migrating an existing pipeline. Used as the language for review text analysis. Review text analysis is supported for English in this version, and any other value is reported as a behavioural difference rather than silently accepted." }, "locationFullName": { "title": "Location name (compatibility)", "type": "string", "description": "Accepted for migrating an existing pipeline. A location name on its own does not resolve to a hotel list page here, so supply the list page URL in Hotel list pages instead. Setting this field records the difference in the run summary rather than guessing a location." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Proxy used to reach Tripadvisor. Residential proxy in the United States is the default and is what the collection was measured against. Each retry is issued a fresh exit, which is the whole point of retrying.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } } }, "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 } } } } } } } } } }