Tripadvisor Hotel Photos and Amenities API: Read the Detail Arrays
Look for one field first: data.photos. In the recorded get-hotel-details run, the data object held two collections, photos and amenitiesScreen, and both were arrays. That is the confirmed surface of the response. It is not a flat hotel record with a name, a rating and a price, and the run does not describe what an item inside either list looks like.
This walk follows those two arrays back through the calls that feed them: a destination lookup, a dated hotel search, and the details request. Each one answers with a different shape under a data key, and that is where most parsers break.
Requests go to https://api.opendata-api.com/api/project/tripadvisor-data/<operationId>?key=YOUR_API_KEY. After you sign in, copy an authorized platform key from the dashboard, keep it in a server-side variable, and treat every URL that contains it as secret. Paths such as data.photos are written relative to the operation payload, the object with status, message, timestamp and data that the gateway returns inside its own data field.
Start at data.photos and data.amenitiesScreen, not a flat hotel record
get-hotel-details requires id, checkIn and checkOut; adults, rooms, childrenAges and currency are optional. The recorded run asked for one hotel over four nights, two adults, one room, in USD. It returned status: true, a message string, an integer timestamp and a data object with the two arrays.
So the answer to getting hotel photos and amenities without parsing hotel HTML is two named arrays in one structured response, not a page to scrape. A documentation example also mentions data.about and nearby attractions, but the recorded run did not confirm them. Build on the arrays, and test anything else on its own terms.
Separate the destination geoId from the hotel detail id
Two identifiers look alike and are not interchangeable. search-location turns a typed name into destination suggestions. The query New York returned a data array of location objects with the declared string fields documentId, secondaryText, title and trackingItems, plus integer geoId values. A documentation example shows HTML-style bold markup in title, so strip tags defensively and let the traveler choose when a name is ambiguous.
A geoId identifies a place. It goes into search-hotels as geoId, sent as a string, next to checkIn and checkOut. It never goes into get-hotel-details, which wants a hotel id taken from a search row. That settles the usual question: a geoId for the search, a hotel id for the details. If you hold coordinates instead of a name, search-hotels-by-location takes latitude and longitude, but no response was recorded for it, so verify its rows before reusing this handoff.
Cross three response envelopes without treating every data as a list
| Call | Read | What it holds |
|---|---|---|
search-location | data | an array of location objects |
search-hotels | data.data | an array of hotel rows |
get-hotel-details | data.photos, data.amenitiesScreen | two arrays inside an object |
One wrapper carries all three, so a single helper that returns the payload is correct for each. What sits under its data is not the same. The destination call hands back a list. The search call hands back an object whose list is one level deeper, which is why the hotel list lives at data.data rather than directly in data; iterating data there yields dictionary keys, not hotels. The details call hands back an object that is not a list at all.
A documentation example lists row fields such as id, title, bubbleRating and cardPhotos, yet the recorded search confirmed only that data.data was an array. Print the keys of a row you actually received before deciding which one is the hotel identifier.
Carry the same stay context into the detail request
Search and details both describe a stay, so keep checkIn, checkOut, adults, rooms and childrenAges identical between them. Note the one naming difference: search calls the currency input currencyCode, details calls it currency. childrenAges is an array of ages from 0 to 17, with 0 meaning under one year; the documented example is [0,10]. No default is documented for guests, rooms or currency, and USD is only an example, so send them explicitly.
The recorded details run used this request shape. Swap in dates that are still in the future:
https://api.opendata-api.com/api/project/tripadvisor-data/get-hotel-details?key=YOUR_API_KEY&id=114811&checkIn=2026-12-10&checkOut=2026-12-14&adults=2&rooms=1¤cy=USD
Whether any of these inputs changes the photo or amenity lists is not established. They are there so the details request describes the same stay as the search it enriches.
Keep collection items intact until their fields are verified
The run proved two arrays, not their contents. So there is no honest photo["url"] or amenity["name"] yet, and guessing one produces code that works on a sample and fails on the next hotel. Store each item exactly as received, beside the hotel id, the stay and a retrieval time. When you later map fields, derive the mapping from items you have in hand and make every access optional.
Give empty, missing, and invalid arrays different outcomes
Four states deserve four outcomes:
- present: a non-empty list. Store it and render what you can verify.
- empty:
[]. A valid response with nothing to show. It does not prove the hotel has no photos or lacks a facility. An empty amenities array is unknown, not a negative, so record it that way. - missing: the key is absent. A coverage or schema gap. Log it and do not render an absence claim.
- invalid: the key exists but is
null, an object or a string. Treat it as a contract change, stop, and report it rather than coercing.
The script below checks three layers in order, HTTP status, the gateway code, then the operation status, because HTTP 200 alone is not a result. It then classifies each array and saves the raw items.
import json
import os
from datetime import date, datetime, timedelta, timezone
import requests
BASE = "https://api.opendata-api.com/api/project/tripadvisor-data"
KEY = os.environ["OPENDATA_API_KEY"] # server-side only; never log the full URL
def call(operation, **params):
"""Return the operation payload: status, message, timestamp, data."""
try:
response = requests.get(
f"{BASE}/{operation}", params={**params, "key": KEY}, timeout=45
)
except requests.RequestException:
raise RuntimeError("transport failure; log a redacted URL") from None
if not response.ok: # HTTP layer
raise RuntimeError(f"HTTP {response.status_code}")
gateway = response.json()
if not isinstance(gateway, dict) or gateway.get("code") != 200:
raise RuntimeError("gateway failure; inspect code and message")
payload = gateway.get("data")
if not isinstance(payload, dict) or payload.get("status") is not True:
raise RuntimeError("operation failure; inspect its message")
return payload
def collection(container, name):
"""Classify one expected array as present, empty, missing or invalid."""
if not isinstance(container, dict) or name not in container:
return "missing", []
items = container[name]
if not isinstance(items, list):
return "invalid", []
return ("present" if items else "empty"), items
check_in = date.today() + timedelta(days=45)
stay = {
"checkIn": check_in.isoformat(),
"checkOut": (check_in + timedelta(days=4)).isoformat(),
"adults": 2,
"rooms": 1,
}
# 1. Destination: data is a list. Confirm the geoId appears in the suggestions.
GEO_ID = 60763 # used in the recorded hotel search
places = call("search-location", query="New York")["data"]
if not isinstance(places, list) or not any(
isinstance(p, dict) and p.get("geoId") == GEO_ID for p in places
):
raise SystemExit("Choose a geoId from the actual suggestions")
# 2. Search: the rows sit one level deeper, at data.data.
kind, rows = collection(
call("search-hotels", geoId=str(GEO_ID), currencyCode="USD", **stay)["data"],
"data",
)
if kind != "present":
raise SystemExit(f"Hotel list is {kind}; nothing to enrich")
print(sorted(rows[0]) if isinstance(rows[0], dict) else type(rows[0]))
# 3. Details: data is an object holding two arrays.
HOTEL_ID = "114811" # id from the recorded run; use a verified row identifier
detail = call("get-hotel-details", id=HOTEL_ID, currency="USD", **stay)["data"]
record = {
"hotelId": HOTEL_ID,
"stay": stay,
"retrievedAt": datetime.now(timezone.utc).isoformat(),
}
for name in ("photos", "amenitiesScreen"):
kind, items = collection(detail, name)
record[name] = {"state": kind, "items": items}
print(name, kind, len(items))
with open("hotel-detail.json", "w", encoding="utf-8") as handle:
json.dump(record, handle, ensure_ascii=False, indent=2)
Know what hotel photos and amenities cannot prove
These two arrays are content, not a booking answer. A response does not confirm room availability, a final price, a reservation or a guarantee that the lists are complete. The search side gives no verified total count, page size or stable ordering, so a shortlist is a snapshot taken at request time. Photos also carry display and image-use permissions of their own, so check what you may show before attaching them to a landing page.
The same project lists other routes that this walk does not validate. A one-way rental car uses search-cars-different-drop-off, and rental details and reviews need a rentalId you already hold. Restaurant lookups should start from get-restaurant-details-v2 rather than the deprecated path. None of these has a recorded response, so test each with your own identifiers before relying on it.