{ "openapi": "3.1.0", "info": { "title": "Tripadvisor API", "version": "1.0.0", "description": "Tripadvisor places, profiles, traveller reviews and gallery photos for hotels, restaurants and attractions, exposed through FetchLayer." }, "servers": [ { "url": "https://api.fetchlayer.dev/tripadvisor" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Send your FetchLayer key as Authorization: Bearer ss-your-key." } } }, "paths": { "/search-locations": { "post": { "operationId": "search-locations", "tags": [ "Places" ], "summary": "Find places by name", "description": "Search Tripadvisor for hotels, restaurants, attractions, tours, cities and regions by name. Each match comes back with the location id the other endpoints take, the kind of place it is, where it sits, its rating and its review count. It returns the closest matches rather than every place that could match, so this is a resolver, not a directory crawl.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Name of a hotel, restaurant, attraction, city or region." }, "locationTypes": { "type": "array", "items": { "type": "string" }, "description": "Narrow to all, hotel, restaurant, attraction, activity and/or geo.", "example": "all" }, "limit": { "type": "number", "description": "Maximum places returned (max 50), or -1 for everything available.", "example": "10" }, "latitude": { "type": "number", "description": "Bias results towards this point (-90 to 90). Pass longitude too." }, "longitude": { "type": "number", "description": "Bias results towards this point (-180 to 180)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "query" ] }, "examples": { "default": { "value": { "query": "Park Hyatt Tokyo", "locationTypes": [ "hotel" ], "limit": 5 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "locations": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "locationId": { "type": "string", "description": "Pass this as location to the profile, reviews and photos endpoints." }, "name": { "type": "string", "description": "The place name as Tripadvisor publishes it." }, "locationType": { "type": "string", "description": "hotel, restaurant, attraction, activity, geo, airline, or other." }, "rawPlaceType": { "type": "string", "description": "Tripadvisor's own wording for the kind of place." }, "parentHierarchy": { "type": "string", "description": "Where the place sits, as Tripadvisor writes it: \"Asakusa, Tokyo Prefecture, Japan\"." }, "city": { "type": "string", "description": "City the place sits in." }, "country": { "type": "string", "description": "Country the place sits in." }, "parentGeoId": { "type": "string", "description": "Tripadvisor id of that city — the handle for destination-level work." }, "latitude": { "type": "number", "description": "Latitude, where Tripadvisor publishes one." }, "longitude": { "type": "number", "description": "Longitude, where Tripadvisor publishes one." }, "rating": { "type": "number", "description": "Average rating out of 5." }, "reviewCount": { "type": "number", "description": "Every review Tripadvisor holds for the place." } } }, "description": "The matching places, closest match first." }, "locationCount": { "type": "number", "description": "Number of places in this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk cut short, a field Tripadvisor does not publish for this place, an upstream limit that was hit. Read it: a response can be well-formed and still incomplete, and this array is where that is said." }, "requestedUrl": { "type": "string", "description": "The Tripadvisor page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO-8601 timestamp of when the data was collected." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "locationCount": 5, "locations": [ { "locationId": "298106", "name": "Park Hyatt Tokyo", "locationType": "hotel", "parentHierarchy": "Shinjuku, Tokyo, Japan", "city": "Tokyo", "country": "Japan", "rating": 4.5, "reviewCount": 2184 } ], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/location-profile": { "post": { "operationId": "location-profile", "tags": [ "Places" ], "summary": "Get a place's profile", "description": "Read one place completely: name and kind, rating and review count with the per-bubble distribution and the count held in each language, ranking within its city, price range, address and coordinates, phone, website, amenities, cuisines, opening hours, award history and description. This is eight upstream operations resolved into one request, and it runs browserless — no page render, no headless Chrome.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string", "description": "Tripadvisor location id, or the URL of a hotel, restaurant or attraction page. Use /search-locations to turn a name into an id." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "location" ] }, "examples": { "default": { "value": { "location": "298106" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "profile": { "type": "object", "additionalProperties": true, "description": "The full place record.", "properties": { "locationId": { "type": "string", "description": "The resolved Tripadvisor location id." }, "name": { "type": "string", "description": "Place name." }, "locationType": { "type": "string", "description": "hotel, restaurant, attraction, activity, geo, airline, or other." }, "isClosed": { "type": "boolean", "description": "Whether Tripadvisor marks the place as permanently closed." }, "rating": { "type": "number", "description": "Average rating out of 5." }, "reviewCount": { "type": "number", "description": "Every review Tripadvisor holds for the place." }, "ratingDistribution": { "type": "object", "additionalProperties": true, "description": "How many reviews gave each bubble rating, as one through five." }, "reviewCountsByLanguage": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Reviews held in each language, most common first. The honest way to size a non-English pull." }, "ranking": { "type": "object", "additionalProperties": true, "description": "Rank and total among comparable places in the city, plus Tripadvisor's own label (\"#118 of 526 hotels in New York City\"). The label is published for hotels only; the numbers are there for every kind of place." }, "priceRange": { "type": "object", "additionalProperties": true, "description": "Typical minimum, maximum and currency, where Tripadvisor publishes one." }, "address": { "type": "object", "additionalProperties": true, "description": "Full address, street, city, state, postal code and two-letter country code." }, "latitude": { "type": "number", "description": "Latitude." }, "longitude": { "type": "number", "description": "Longitude." }, "phone": { "type": "string", "description": "Published phone number." }, "website": { "type": "string", "description": "The place's own website." }, "amenities": { "type": "array", "items": { "type": "string" }, "description": "Facilities the place lists." }, "cuisines": { "type": "array", "items": { "type": "string" }, "description": "Cuisine tags, for restaurants." }, "hoursOfOperation": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Opening intervals per day, 24-hour HH:MM. A day with no published hours returns no entry." }, "awards": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Travellers' Choice and similar awards, with their years." }, "geoHierarchy": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "The city, region and country the place sits under, with their geo ids." }, "photoCount": { "type": "number", "description": "Photos in the gallery — what /location-photos can page through." }, "description": { "type": "string", "description": "The place description Tripadvisor publishes." } } }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk cut short, a field Tripadvisor does not publish for this place, an upstream limit that was hit. Read it: a response can be well-formed and still incomplete, and this array is where that is said." }, "requestedUrl": { "type": "string", "description": "The Tripadvisor page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO-8601 timestamp of when the data was collected." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "locationId": "298106", "profile": { "locationId": "298106", "name": "Park Hyatt Tokyo", "locationType": "hotel", "rating": 4.5, "reviewCount": 2184, "ratingDistribution": { "one": 22, "two": 41, "three": 158, "four": 583, "five": 1380 }, "ranking": { "rank": 12, "total": 1489, "label": "#12 of 1,489 hotels in Tokyo" }, "reviewCountsByLanguage": [ { "language": "en", "count": 1204 }, { "language": "ja", "count": 486 } ] }, "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/location-reviews": { "post": { "operationId": "location-reviews", "tags": [ "Reviews" ], "summary": "Get a place's reviews", "description": "Pull traveller reviews for one place: rating, title and the full text, the trip type, the month of the visit and the date it was written, the reviewer's display name, home town and contribution count, per-aspect sub-ratings, attached photo URLs, and the owner's public reply where there is one. Tripadvisor serves 20 reviews per page whatever limit asks for, so depth comes from pages and cursor, not from a bigger page.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string", "description": "Tripadvisor location id, or the URL of a hotel, restaurant or attraction page. Use /search-locations to turn a name into an id." }, "limit": { "type": "number", "description": "Maximum reviews returned (max 2000), or -1 for everything available. Reviews still arrive 20 per page.", "example": "20" }, "pages": { "type": "number", "description": "Pages of reviews to collect in one request (max 100), or -1 for the maximum allowed. 20 reviews per page — this is the knob that controls depth.", "example": "1" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "language": { "type": "string", "description": "Language to request reviews in. A translation target, not a filter — Tripadvisor still returns reviews written in a mix of languages. Pair it with translate to get the text in this language.", "example": "en" }, "translate": { "type": "boolean", "description": "Return each review's text translated into language.", "example": "false" }, "sortBy": { "type": "string", "description": "recent, detailed, or insightful.", "example": "recent" }, "minRating": { "type": "number", "description": "Only reviews rated this many bubbles or more (1 to 5)." }, "tripTypes": { "type": "array", "items": { "type": "string" }, "description": "Only reviews from these trip types: business, couples, family, friends, solo." }, "photosPerReview": { "type": "number", "description": "How many photo URLs to return per review (max 20). 0 skips them.", "example": "4" }, "delayMs": { "type": "number", "description": "Milliseconds to wait between pages (max 30000)." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "location" ] }, "examples": { "default": { "value": { "location": "298106", "pages": 5, "sortBy": "recent", "minRating": 4, "photosPerReview": 4 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reviews": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "reviewId": { "type": "string", "description": "Stable review id — the dedupe key for incremental pulls." }, "rating": { "type": "number", "description": "Bubble rating, 1 to 5." }, "title": { "type": "string", "description": "Review headline." }, "text": { "type": "string", "description": "The full review, not a snippet." }, "language": { "type": "string", "description": "The language this text is returned in." }, "originalLanguage": { "type": "string", "description": "The language the reviewer wrote in, which may differ." }, "isTranslated": { "type": "boolean", "description": "True when text is a translation rather than the reviewer's own words." }, "publishedDate": { "type": "string", "description": "When the review was written, YYYY-MM-DD." }, "visitDate": { "type": "string", "description": "When the reviewer says they visited, YYYY-MM-DD." }, "tripType": { "type": "string", "description": "business, couples, family, friends, or solo." }, "helpfulVotes": { "type": "number", "description": "How many people marked the review helpful." }, "photoUrls": { "type": "array", "items": { "type": "string" }, "description": "Photos the reviewer attached. URLs only — stream the bytes from GET /media." }, "subRatings": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Per-aspect ratings (location, cleanliness, service, value…), where the place collects them." }, "reviewer": { "type": "object", "additionalProperties": true, "description": "Display name, username, profile URL, stated home town, country code, contribution count, helpful votes and avatar." }, "managementResponse": { "type": "object", "additionalProperties": true, "description": "The owner's public reply: text, published date, respondent name and role." } } }, "description": "The reviews collected, 20 per page walked." }, "filters": { "type": "object", "additionalProperties": true, "description": "The filters this pull actually ran with, after defaults were applied — including the resolved language and translate." }, "reviewCount": { "type": "number", "description": "Every review Tripadvisor holds for this place under the requested language, not just this page. Changing language moves this number without changing which rows come back." }, "returnedCount": { "type": "number", "description": "Reviews in this response." }, "pagesScraped": { "type": "number", "description": "Pages actually collected. Each page counts as one request against your plan." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the listing is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more reviews are available beyond this response." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk cut short, a field Tripadvisor does not publish for this place, an upstream limit that was hit. Read it: a response can be well-formed and still incomplete, and this array is where that is said." }, "requestedUrl": { "type": "string", "description": "The Tripadvisor page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO-8601 timestamp of when the data was collected." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "locationId": "298106", "locationName": "Park Hyatt Tokyo", "reviewCount": 2184, "returnedCount": 100, "pagesScraped": 5, "hasNextPage": true, "nextCursor": "eyJvZmZzZXQiOjEwMH0", "reviews": [ { "reviewId": "948273615", "rating": 5, "title": "Still the best view in Tokyo", "text": "The room was immaculate and the staff remembered our names from a stay two years ago…", "publishedDate": "2026-08-29", "visitDate": "2026-08-01", "tripType": "couples", "reviewer": { "displayName": "Marina K", "location": "Melbourne, Australia", "contributionCount": 214 }, "managementResponse": { "respondentName": "Front Office Manager", "text": "Thank you for staying with us again…" } } ], "notes": [ "Tripadvisor serves 20 reviews per page; limit above that is satisfied by walking pages." ] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/location-photos": { "post": { "operationId": "location-photos", "tags": [ "Photos" ], "summary": "Get a place's photos", "description": "Page through a place's gallery. Each photo comes back as a Tripadvisor URL with its caption, pixel dimensions, media type and credit, plus a download URL that streams the file itself through this API.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "location": { "type": "string", "description": "Tripadvisor location id, or the URL of a hotel, restaurant or attraction page. Use /search-locations to turn a name into an id." }, "limit": { "type": "number", "description": "Maximum photos returned (max 200), or -1 for everything available.", "example": "20" }, "cursor": { "type": "string", "description": "Resume from a previous response's nextCursor." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "location" ] }, "examples": { "default": { "value": { "location": "298106", "limit": 50 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "photoId": { "type": "string", "description": "Tripadvisor photo id." }, "caption": { "type": "string", "description": "Caption, where one is published." }, "url": { "type": "string", "description": "Original Tripadvisor image URL." }, "downloadUrl": { "type": "string", "description": "FetchLayer download URL — pass it to GET /media to stream the bytes." }, "width": { "type": "number", "description": "Pixel width." }, "height": { "type": "number", "description": "Pixel height." }, "attribution": { "type": "string", "description": "Who supplied the photo — the property, or a traveller." } } }, "description": "The gallery photos." }, "photoCount": { "type": "number", "description": "Number of photos in this response." }, "nextCursor": { "type": "string", "description": "Pass back as cursor to continue, or null when the gallery is exhausted." }, "hasNextPage": { "type": "boolean", "description": "Whether more photos are available." }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Caveats about this specific result — a walk cut short, a field Tripadvisor does not publish for this place, an upstream limit that was hit. Read it: a response can be well-formed and still incomplete, and this array is where that is said." }, "requestedUrl": { "type": "string", "description": "The Tripadvisor page this result corresponds to." }, "scrapedAt": { "type": "string", "description": "ISO-8601 timestamp of when the data was collected." }, "blocked": { "type": "boolean", "description": "Always false on a successful response." } }, "additionalProperties": false }, "examples": { "default": { "value": { "locationId": "298106", "photoCount": 50, "hasNextPage": true, "photos": [ { "photoId": "512348891", "caption": "Deluxe King room, 52nd floor", "url": "https://media-cdn.tripadvisor.com/media/photo-o/…", "width": 1600, "height": 1067, "attribution": "Management" } ], "notes": [] } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/media": { "get": { "operationId": "media", "tags": [ "Photos" ], "summary": "Download a place photo", "description": "Stream a photo's actual bytes, using a url taken from a photo or from a review's photoUrls. Only Tripadvisor's own image hosts are accepted. HTTP Range requests are supported. This is a GET with query parameters, not a JSON POST, and it bills as one request.", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Tripadvisor photo URL, as returned on a photo or a review. Passed as a query parameter.", "schema": { "type": "string" } }, { "name": "filename", "in": "query", "required": false, "description": "Content-Disposition filename to serve the file as (max 200 characters).", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "Standard HTTP Range request header, for example bytes=0-65535. Sent as a header, not a query parameter.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } }, "/resolve-url": { "post": { "operationId": "resolve-url", "tags": [ "Utility" ], "summary": "Parse a Tripadvisor URL", "description": "Turn any Tripadvisor URL into the identifiers it encodes — the location id, the geo id of the city or region, a review id, a photo id, the position in the review list it points at, and the kind of place. Use it to go from a link somebody pasted to the id the other endpoints need. Parsing a URL does not consume a credit.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Any Tripadvisor URL, to be parsed into structured identifiers." }, "format": { "type": "string", "description": "json or markdown.", "example": "json" } }, "additionalProperties": false, "required": [ "url" ] }, "examples": { "default": { "value": { "url": "https://www.tripadvisor.com/Hotel_Review-g1066443-d298106-Reviews-Park_Hyatt_Tokyo-Shinjuku_Tokyo_Tokyo_Prefecture_Kanto.html" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "What the URL points at: location, review, photo, geo, or unknown." }, "locationId": { "type": "string", "description": "The place the URL names — pass it straight to the other endpoints." }, "geoId": { "type": "string", "description": "The city or region the URL names." }, "reviewId": { "type": "string", "description": "Present when the URL points at one review." }, "photoId": { "type": "string", "description": "Present when the URL points at one photo." }, "reviewOffset": { "type": "number", "description": "Position in the review list the URL points at." }, "pageType": { "type": "string", "description": "Tripadvisor's own name for the page." }, "locationType": { "type": "string", "description": "hotel, restaurant, attraction, activity, geo, airline, or other." }, "slug": { "type": "string", "description": "The readable name in the URL. Not an identifier." } }, "additionalProperties": false }, "examples": { "default": { "value": { "kind": "location", "locationId": "298106", "geoId": "1066443", "locationType": "hotel", "slug": "Park_Hyatt_Tokyo" } } } } } }, "401": { "description": "Invalid or missing Bearer token" } }, "security": [ { "BearerAuth": [] } ] } } } }