# TripAdvisor Listings

Extract TripAdvisor listing data on hotels, restaurants, and attractions: contact details, ratings, rankings, amenities, cuisines, opening hours, hotel offers, and bookable tickets.

**Pricing:** $2 / 1k listings

**Endpoint:** `POST /api/v1/agents/tripadvisor/listings/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | A location name or keyword to search, e.g. 'Paris' or 'Eiffel Tower'. Use English place names for best coverage. (By Search mode.) |
| `startUrls` | array | No | One per line. TripAdvisor search or location (place) page URLs to extract. (By URL mode.) |
| `maxResults` | integer | No | Places per query / URL. Use 0 for all. |
| `placeTypes` | array | No | Which kinds of places to include. |
| `language` | string | No | Language for the listing data. |
| `currency` | string | No | Currency for prices. |
| `includeTags` | boolean | No | Pull review category tags (e.g. "Family-friendly", "Romantic"). |
| `checkInDate` | date | No | Hotel-only: check-in date for room pricing and offers. |
| `checkOutDate` | date | No | Hotel-only: check-out date for room pricing and offers. |
| `includePriceOffers` | boolean | No | Improves coverage of bookable hotel offers (works best with check-in / check-out dates set). |
| `maxPhotosPerPlace` | integer | No | Photos to fetch per place. Use 0 for all. |
| `photosType` | string | No | Which photo source to pull from. |

## Example

```bash
curl -X POST https://api.mindcase.co/api/v1/agents/tripadvisor/listings/run \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/api/v1/agents/tripadvisor/listings/run",
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {}},
)
data = resp.json()
```

## Get the results

`run` is async and returns a `job_id`. Poll until `status` is `completed`, then read the rows:

```bash
# 1) check status
curl https://api.mindcase.co/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/api/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, endpoints): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `name` | Name | text |
| `localName` | Local Name | text |
| `tripadvisorUrl` | TripAdvisor URL | url |
| `type` | Type | text |
| `subcategories` | Subcategories | array |
| `description` | Description | text |
| `address` | Address | text |
| `addressDetails` | Address Details | object |
| `localAddress` | Local Address | text |
| `localLanguage` | Local Language | text |
| `location` | Location | text |
| `neighborhoods` | Neighborhoods | object_array |
| `latitude` | Latitude | number |
| `longitude` | Longitude | number |
| `nearestMetroStations` | Nearest Metro Stations | object_array |
| `phone` | Phone | phone |
| `email` | Email | email |
| `website` | Website | url |
| `rating` | Rating | rating |
| `reviews` | Reviews | number |
| `ratingBreakdown` | Rating Breakdown | object |
| `categoryScores` | Category Scores | object_array |
| `reviewTags` | Review Tags | object_array |
| `rank` | Rank | number |
| `rankOutOf` | Rank Out Of | number |
| `rankingString` | Ranking String | text |
| `rawRanking` | Raw Ranking | number |
| `priceLevel` | Price Level | text |
| `photo` | Photo | url |
| `photos` | Photos | array |
| `photoCount` | Photo Count | number |
| `hotelClass` | Hotel Class | text |
| `rooms` | Rooms | number |
| `amenities` | Amenities | array |
| `priceRange` | Price Range | text |
| `checkInDate` | Check-In Date | text |
| `checkOutDate` | Check-Out Date | text |
| `hotelOffers` | Hotel Offers | object_array |
| `roomTips` | Room Tips | object_array |
| `cuisines` | Cuisines | array |
| `mealTypes` | Meal Types | array |
| `dietaryRestrictions` | Dietary Restrictions | array |
| `popularDishes` | Popular Dishes | array |
| `features` | Features | array |
| `establishmentTypes` | Establishment Types | array |
| `openingHours` | Opening Hours | object_array |
| `timezone` | Timezone | text |
| `claimed` | Claimed | boolean |
| `menuUrl` | Menu URL | url |
| `orderOnline` | Order Online | object_array |