tripadvisor-api

TripAdvisor Terra API via curl (no MCP)

TripAdvisor's Terra API (terra.tripadvisor.com/api) is a plain API-key REST API reachable directly from a server or shell — no browser bridge needed. This skill shells out to curl with the key in an X-API-Key header, exactly as tripadvisor-mcp's src/client.ts does. Terra is the current API (the legacy Content API sunsets 2026-08-31); it has no write endpoints — everything here is a read.

A second, smaller tier at the bottom covers the one thing Terra can't do without a key: reading a location's core details from the public consumer page via the fpx browser bridge.

One-time setup: get a Terra key

# Prefer the env var tripadvisor-mcp itself reads (check its .env first):
grep -h TRIPADVISOR_API_KEY ~/git/tripadvisor-mcp/.env 2>/dev/null
export TRIPADVISOR_API_KEY='...'

If you don't have one: create a free Discover-tier key at https://www.tripadvisor.com/developers (pay-as-you-go, 10 QPS / 10,000 calls/day). A legacy Content API key does NOT work here (and vice versa) — a mismatched key gets a 403.

Core call pattern

BASE=https://terra.tripadvisor.com/api

curl -sS "$BASE/locations/search?query=Golden%20Gate%20Bridge" \
  -H "X-API-Key: $TRIPADVISOR_API_KEY" -H 'accept: application/json' \
  | jq '.data[].location | {id, name: (.names[] | select(.primary) | .value)}'

Every call needs just the two headers above — no session/cookie, no mutual TLS. Ready-to-run recipes for all 6 endpoints are in references/terra-endpoints.md.

The one rule: resolve a location id first

Details/photos/reviews are keyed by numeric location_id — get one from ta_search_locations's equivalent, GET /locations/search, before calling the id-scoped endpoints:

curl -sS "$BASE/locations/search?query=Golden+Gate+Bridge" \
  -H "X-API-Key: $TRIPADVISOR_API_KEY" | jq -r '.data[].location.id'
# 104675

Response shapes (quick reference)

• List endpoints (search, nearby, reviews, photos) wrap results: {"data": [...], "pagination": {"page","size","total_pages","total_elements"}}.
• GET /locations (batch) and GET /locations/{id} (details) do not wrap in pagination — batch returns {"data": [...]}, details returns the location object directly.
• A location object keys names/descriptions/addresses as arrays tagged by language — the primary entry has "primary": true (jq '.names[] | select(.primary) | .value'), not a flat name field.

Full field lists and all 6 curl+jq recipes: references/terra-endpoints.md.

Output / error contract

• A 2xx body is JSON; pipe to jq.
• 400 — validation error; body is {type, title, status, detail, field_errors: [{field, message}], trace_id} — detail/field_errors name the bad param.
• 401/403 — key missing, invalid, or the wrong API family (legacy key on Terra, or vice versa).
• 404 — unknown id, or a typo'd path (/locations/{id} is plural; the singular form 404s).
• 429 — QPS (10) or daily quota (10,000) exceeded on the Discover tier; back off and retry (the response may carry Retry-After).

Fallback tier: no API key (fpx browser bridge)

TripAdvisor's consumer site (www.tripadvisor.com) is DataDome-walled, so it can't be curled directly — but a location's public detail page is plain server-rendered HTML with a clean application/ld+json block (name, rating, review count, address, phone, coordinates), reachable with no API key by routing the fetch through your own signed-in browser tab via fpx (@fetchproxy/cli). Use this when you don't have (or don't want to use) a Terra key, or ta_get_location_details is blocked.

npm install -g @fetchproxy/cli                      # provides `fpx`
fpx profile add tripadvisor --domain tripadvisor.com # fetch capability only
fpx pair -p tripadvisor                              # prints a pair code → approve in Transporter

Requires the Transporter extension with an open www.tripadvisor.com tab. This covers attractions, hotels, and restaurants — it does not return individual review text (only the aggregate rating/count). Fetch + parse recipe: references/web-fallback.md.

fpx exit codes (fetch verbs)

• 0 — success.
• 2 — bridge unavailable: extension not connected / pairing pending → fpx pair -p tripadvisor.
• 3 — bot wall: the tab hasn't cleared DataDome → open/refresh a www.tripadvisor.com tab and retry.
• 4 — upstream non-2xx from TripAdvisor.

Notes

• Terra reads only — nothing here mutates TripAdvisor data.
• This project (tripadvisor-mcp) is developed and maintained by AI (Claude Code).