{
  "openapi": "3.0.1",
  "info": {
    "title": "TripAdvisor Restaurant Reviews Scraper — Diner Reviews, Ratings",
    "description": "TripAdvisor restaurant reviews and attraction reviews by URL or name. One row per review: bubbles, text, food, service, value, atmosphere ratings, visit date, diner tips, photos, owner reply. Free location row: rating, review count, cuisine, menu, hours. Filters: negative reviews, new reviews only.",
    "version": "1.2",
    "x-build-id": "8TupSjaBPg4AS41fX"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kestrel~tripadvisor-restaurant-reviews/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kestrel-tripadvisor-restaurant-reviews",
        "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~tripadvisor-restaurant-reviews/runs": {
      "post": {
        "operationId": "runs-sync-kestrel-tripadvisor-restaurant-reviews",
        "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~tripadvisor-restaurant-reviews/run-sync": {
      "post": {
        "operationId": "run-sync-kestrel-tripadvisor-restaurant-reviews",
        "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": {
          "restaurantNames": {
            "title": "Restaurant names",
            "uniqueItems": true,
            "type": "array",
            "description": "Restaurant or attraction names, ideally with the city, e.g. [\"Cervejaria Ramiro, Lisbon\", \"Oceanário de Lisboa\"]. Use for \"reviews of restaurant X\". Resolved through TripAdvisor's own typeahead; a hit must share at least half of your words, so a name TripAdvisor does not know ends as a free error row, never as a random bistro — check location_name and location_type in the location and status rows. Empty (default) = none; one of restaurantNames, startUrls or locationIds is required.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "TripAdvisor restaurant or attraction URLs",
            "uniqueItems": true,
            "type": "array",
            "description": "TripAdvisor restaurant or attraction pages on any country site, e.g. [\"https://www.tripadvisor.com/Restaurant_Review-g189158-d2703366-Reviews-Cervejaria_Ramiro-Lisbon.html\"] or an Attraction_Review URL; ShowUserReviews deep links work too. Only the numeric d<id> matters. Hotel URLs are refused before anything is charged (use kestrel/tripadvisor-reviews-scraper). Empty (default) = none.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "locationIds": {
            "title": "TripAdvisor location ids",
            "uniqueItems": true,
            "type": "array",
            "description": "TripAdvisor location ids, the number after \"d\" in a restaurant or attraction URL, e.g. [\"2703366\", \"d190147\"] — what an earlier run's location_id gives you. The fastest path (no lookup) and the way to re-read the same places on a schedule; TripAdvisor resolves whether the id is a restaurant or an attraction. A hotel id ends as status wrong_type and an unknown id as not_found, both free. Empty (default) = none.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "locationType": {
            "title": "Location type",
            "enum": [
              "any",
              "restaurant",
              "attraction"
            ],
            "type": "string",
            "description": "\"any\" (default) = restaurants and attractions. \"restaurant\" or \"attraction\" = only that family: a target of the other family is reported as status wrong_type after one page and never charged. Hotels are wrong_type whatever you choose. Use \"restaurant\" when the user says \"restaurants only\".",
            "default": "any"
          },
          "maxReviewsPerLocation": {
            "title": "Max reviews per location and language",
            "minimum": 0,
            "maximum": 20000,
            "type": "integer",
            "description": "The main cost control: the newest N reviews per location and language are read, e.g. 50 (default 100, maximum 20000), at most N × $0.005 ($0.50 at the default). 0 = every review the site lists (15 per page on restaurants, 10 on attractions; busy places run into the thousands). Filters apply AFTER this cap: 100 with maxRating 2 delivers only the low-rated reviews among the newest 100, so pair a filter with 0 or with sinceDate when the user wants all of them.",
            "default": 100
          },
          "sinceDate": {
            "title": "Only reviews published on or after",
            "type": "string",
            "description": "Only reviews published on or after this date: \"2026-06-01\", or relative so a schedule never goes stale: \"30 days\", \"2 weeks\", \"6 months\". Reviews come newest first, so reading stops once a whole page is older — a daily run with \"2 days\" reads one or two pages per restaurant and bills only the new reviews. Empty (default) = no date limit. Use for \"new reviews only\" and review monitoring.",
            "default": ""
          },
          "maxRating": {
            "title": "Only reviews at or below this rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "0 (default) = every rating. 1-5 = keep only reviews with that many bubbles or fewer, e.g. 2 for a complaints feed across a restaurant group (\"negative reviews only\"), 3 to include the middling ones. Filtered reviews are never billed; the pages are still read. Applied to the reviews read under maxReviewsPerLocation, so use 0 or a sinceDate for a complete list of negative reviews.",
            "default": 0
          },
          "tripTypes": {
            "title": "Trip types",
            "uniqueItems": true,
            "type": "array",
            "description": "Keep only reviews from these trip types, e.g. [\"family\"] or [\"couples\", \"friends\"]; allowed: family, couples, solo, business, friends. Empty (default) = all. Filtered reviews are never billed. TripAdvisor no longer publishes a meal type (breakfast/lunch/dinner), so trip type is the visit context it does carry.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "languages": {
            "title": "Review languages",
            "uniqueItems": true,
            "type": "array",
            "description": "Availability: the zh site failed live checks on 2026-10-16; Chinese collection is currently unverified. Use [\"en\"] for the tested example. Each language selects a TripAdvisor country site, not a translation target. includeTranslated=false keeps original reviews; filters apply after maxReviewsPerLocation. Each language is a separate job and bill, and translated duplicates can recur across languages. See README for supported site codes.",
            "default": [
              "en"
            ],
            "items": {
              "type": "string"
            }
          },
          "includeTranslated": {
            "title": "Include machine-translated reviews",
            "type": "boolean",
            "description": "true (default) = keep the machine-translated reviews each site shows (rows carry translated: true and original_language). false = only reviews written in that site's language — with several languages this also stops one review being billed once per language. Use false for \"Italian reviews written by Italian diners\".",
            "default": true
          },
          "requireText": {
            "title": "Only reviews with a written text",
            "type": "boolean",
            "description": "true = drop rating-only reviews before billing. false (default) = keep them. TripAdvisor reviews almost always carry text, so this rarely removes much.",
            "default": false
          },
          "includeLocationRow": {
            "title": "Include a location row",
            "type": "boolean",
            "description": "true (default) = also emit one free row per location and language (type \"location\"): name and type, bubble rating, review count, reviews per rating and per language, food/service/value/atmosphere averages, city ranking (\"#12 of 4,870 restaurants in Lisbon\"), cuisines, price band, dish tags, category tags, address, coordinates, phone, e-mail, website, menu link, opening hours, open-now and permanently-closed flags. Never charged. false = review and status rows only.",
            "default": true
          },
          "sessions": {
            "title": "Parallel sessions",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "Residential proxy sessions (egress IPs) reading in parallel, 1 to 16, e.g. 4 (default 2). More is faster for many locations; each session is paced separately. Does not change the bill.",
            "default": 2
          },
          "perIp": {
            "title": "Requests per second per session",
            "minimum": 0.1,
            "maximum": 3,
            "type": "number",
            "description": "Requests per second per session, 0.1 to 3 (default 1). TripAdvisor serves about 1 page per second per IP; raising it causes IP rotations, not speed. Leave the default.",
            "default": 1
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Keep the default: Apify Proxy, RESIDENTIAL group ({\"useApifyProxy\": true, \"apifyProxyGroups\": [\"RESIDENTIAL\"]}). TripAdvisor's bot gate refuses every datacenter IP, so any other proxy fails every page before anything is charged.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}