# Trip.com Hotel Search & Nightly Price Finder (`dataspryva/trip-com-hotel-search-and-nightly-price-finder`) Actor

Search Trip.com hotels by city and travel dates, or fetch one hotel by ID, with nightly price, star rating, guest score, amenities, and location.

- **URL**: https://apify.com/dataspryva/trip-com-hotel-search-and-nightly-price-finder.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** Travel, Automation, E-commerce
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Trip.com Hotel Search & Nightly Price Finder

Find hotels on Trip.com for a city and stay dates — or pull the complete profile for properties you already know. Every row is a ready-to-use hotel record with its nightly rate, star class, guest score, location, room details and a direct booking link.

### Modes

#### Search hotels by city and dates (`searchHotels`)

Give a city and optional stay dates and filters. The actor resolves the city through Trip.com's own search service, reads the server-rendered result pages, and returns hotels with the price quoted for your exact dates.

- **Pagination that actually advances:** Trip.com serves about 12 hotels per result query and ignores page-number parameters. The actor slices the result space across star classes and city zones, de-duplicates by hotel ID, and keeps going until your `maxItems` is reached or the source is exhausted.
- **Date-aware prices:** nightly price before tax, nightly price after tax, and the total for the whole stay are all included.
- **Filters that change the result set:** star range, guest score, nightly budget, breakfast, free cancellation, pay-at-hotel.
- **Optional detail enrichment:** turn on `includeDetails` to add the full street address, facilities, description, phone, e-mail and check-in/out times to every search row.

#### Hotel details by ID or URL (`hotelDetail`)

Paste one or many Trip.com hotel IDs (or full detail URLs). The actor returns the full property profile — address, facilities, description, policies, photos, contact details, coordinates — and makes a best-effort merge of the current nightly price for your dates when the property appears in the city search.

IDs are taken from `hotelIds`, and the single `hotelId` field is combined with it, so both old and new tasks work.

### Input

| Field | Type | Default | Notes |
|---|---|---|---|
| `mode` | select | `searchHotels` | `searchHotels` or `hotelDetail` |
| `cityName` | text | `London` | City, or a city + country such as `Paris, France` |
| `cityId` | integer | – | Exact Trip.com geo code; overrides the city name |
| `checkIn` / `checkOut` | text | tomorrow / next night | `YYYY-MM-DD` |
| `adults` | integer | 2 | 1–8 adults per room |
| `rooms` | integer | 1 | 1–5 rooms |
| `minStars` / `maxStars` | integer | – | Official star class 1–5 |
| `minRating` | number | – | Guest score 0–10 |
| `maxPrice` | number | – | Nightly budget before taxes |
| `breakfastIncluded` | boolean | false | Only breakfast-included rates |
| `freeCancellation` | boolean | false | Only free-cancellation rates |
| `payAtHotel` | boolean | false | Only pay-at-property rates |
| `sortBy` | select | `recommended` | `priceLow`, `priceHigh`, `rating`, `stars` |
| `currency` | select | `USD` | 16 major currencies |
| `includeDetails` | boolean | false | Enrich every search row from its detail page |
| `maxItems` | integer | 20 | 1–200 |
| `hotelId` | text | – | One hotel ID or detail URL (detail mode) |
| `hotelIds` | string list | – | Multiple hotel IDs or URLs (detail mode) |
| `proxyConfiguration` | proxy | direct | Optional; an Apify Proxy fallback is automatic if Trip.com blocks the datacenter IP |

Saved tasks that still send older keys — `destination`, `city`, `query`, `searchQuery`, `searchQueries`, `checkin`, `checkout`, `check_in`, `check_out`, `adult`, `roomQuantity`, `sort`, `maxResults` — keep working because those keys are mapped in code, even when the input form fills the new defaults.

### Output

Each dataset row is one hotel.

- `hotelId`, `name`, `hotelType`
- `address`, `neighborhood`, `positionDesc`, `city`, `province`, `country`
- `starRating`, `rating`, `ratingText`, `reviewCount`, `subScores`, `locationScore`
- `pricePerNight` — nightly rate before taxes
- `priceWithTax` — nightly rate including taxes and fees
- `priceWithTaxTotal` — full-stay total including taxes and fees
- `currency`, `priceExplanation`, `paymentPolicy`
- `freeCancellation`, `breakfastIncluded`
- `roomName`, `bedType`
- `amenities[]`, `highlights[]`, `description`
- `checkInTime`, `checkOutTime`, `phone`, `email`
- `openYear`, `renovationYear`
- `url`, `thumbnailUrl`, `imageCount`, `imageUrls[]`
- `lat`, `lon`
- `checkIn`, `checkOut`, `recordType`, `scrapedAt`

Empty values are omitted, never returned as `null`.

### Examples

Search London for a two-night stay:

```json
{
  "mode": "searchHotels",
  "cityName": "London",
  "checkIn": "2026-11-20",
  "checkOut": "2026-11-22",
  "maxItems": 50
}
```

Four- and five-star hotels under 300 USD with a guest score of at least 8.5:

```json
{
  "mode": "searchHotels",
  "cityName": "Tokyo",
  "checkIn": "2026-11-20",
  "checkOut": "2026-11-22",
  "minStars": 4,
  "minRating": 8.5,
  "maxPrice": 300,
  "sortBy": "priceLow",
  "maxItems": 40
}
```

Fetch one property, or several at once:

```json
{
  "mode": "hotelDetail",
  "hotelIds": ["731904", "https://www.trip.com/hotels/detail/?hotelId=3037865"],
  "checkIn": "2026-11-20",
  "checkOut": "2026-11-22"
}
```

### Use cases

- **Price monitoring:** rerun the same city, dates and filters to watch nightly rates move.
- **Shortlist building:** combine star, score and budget filters to narrow a destination.
- **Property research:** pull facilities, policies and contact details for a list of known hotels.
- **Travel content:** compare scores, room types and locations across a city.
- **Budget planning:** cap the nightly price and see what remains available.

### FAQ

**Do I need a Trip.com account or cookie?**
No. City search, hotel search and detail pages are read without logging in.

**Why does a search stop before `maxItems`?**
Trip.com returns roughly 12 hotels per result query. The actor walks star and zone slices until it reaches your limit or the source runs out of matching properties. Small cities and very narrow filters can exhaust the source sooner; the status message reports the real count.

**Are prices per night or for the whole stay?**
`pricePerNight` and `priceWithTax` are nightly. `priceWithTaxTotal` is the whole-stay total and matches the breakdown text in `priceExplanation`.

**What is the difference between search and detail prices?**
Search rows always carry the live price for the requested dates. Detail rows try to merge the current price from the same city search. If the property has no availability, or does not appear in the search slices for those dates, the price fields are omitted.

**Why are some fields missing on a row?**
Trip.com does not publish every field for every property — for example, some hotels have no guest reviews, e-mail or neighborhood. Missing fields are omitted rather than filled with placeholders. `includeDetails` fills the largest set of fields.

**Why is the address sometimes just a district in a search row?**
Search result cards expose only the district. Enable `includeDetails`, or use `hotelDetail`, to get the full street address.

**Is this affiliated with Trip.com?**
No. This is an independent third-party tool and is not operated by or affiliated with Trip.com or Ctrip.

# Actor input Schema

## `mode` (type: `string`):

Choose 'Search hotels' to browse a city, or 'Hotel details by ID' to fetch specific properties.

## `cityName` (type: `string`):

City to search, e.g. London, Paris, Tokyo, Bangkok, Dubai. Country names also work: 'Paris, France'.

## `cityId` (type: `integer`):

Exact Trip.com geo code, if you already know it (London = 338). Overrides the city name.

## `checkIn` (type: `string`):

YYYY-MM-DD. Leave blank for tomorrow.

## `checkOut` (type: `string`):

YYYY-MM-DD. Leave blank for the night after check-in.

## `adults` (type: `integer`):

Number of adults per room (1-8).

## `rooms` (type: `integer`):

Number of rooms (1-5).

## `minStars` (type: `integer`):

Lowest official star class to include (1-5).

## `maxStars` (type: `integer`):

Highest official star class to include (1-5).

## `minRating` (type: `number`):

Trip.com guest score on a 0-10 scale, e.g. 8 for 'Very good'.

## `maxPrice` (type: `number`):

Highest nightly room price in the selected currency, before taxes.

## `breakfastIncluded` (type: `boolean`):

Only return rooms whose rate includes breakfast.

## `freeCancellation` (type: `boolean`):

Only return rooms with a free-cancellation policy.

## `payAtHotel` (type: `boolean`):

Only return rooms that can be paid for at the property.

## `sortBy` (type: `string`):

Order of the returned hotels. Price and rating sorts scan extra result slices before trimming.

## `currency` (type: `string`):

Currency for all price fields.

## `includeDetails` (type: `boolean`):

Fetch each hotel's detail page for its full address, facilities, description, phone and check-in times. Adds one request per hotel.

## `maxItems` (type: `integer`):

Maximum records to return (1-200).

## `hotelId` (type: `string`):

One Trip.com hotel ID or detail URL, e.g. 731904. Used when mode is 'Hotel details by ID'.

## `hotelIds` (type: `array`):

Multiple Trip.com hotel IDs or detail URLs. Combined with 'hotelId' when both are provided.

## `proxyConfiguration` (type: `object`):

Optional. Leave unchanged for a direct connection; the actor uses Apify Proxy automatically if Trip.com blocks the datacenter IP.

## Actor input object example

```json
{
  "mode": "searchHotels",
  "cityName": "London",
  "checkIn": "",
  "checkOut": "",
  "adults": 2,
  "rooms": 1,
  "breakfastIncluded": false,
  "freeCancellation": false,
  "payAtHotel": false,
  "sortBy": "recommended",
  "currency": "USD",
  "includeDetails": false,
  "maxItems": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `items` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "searchHotels",
    "cityName": "London",
    "checkIn": "",
    "checkOut": "",
    "adults": 2,
    "rooms": 1,
    "breakfastIncluded": false,
    "freeCancellation": false,
    "payAtHotel": false,
    "sortBy": "recommended",
    "currency": "USD",
    "includeDetails": false,
    "maxItems": 5,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/trip-com-hotel-search-and-nightly-price-finder").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "searchHotels",
    "cityName": "London",
    "checkIn": "",
    "checkOut": "",
    "adults": 2,
    "rooms": 1,
    "breakfastIncluded": False,
    "freeCancellation": False,
    "payAtHotel": False,
    "sortBy": "recommended",
    "currency": "USD",
    "includeDetails": False,
    "maxItems": 5,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/trip-com-hotel-search-and-nightly-price-finder").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "searchHotels",
  "cityName": "London",
  "checkIn": "",
  "checkOut": "",
  "adults": 2,
  "rooms": 1,
  "breakfastIncluded": false,
  "freeCancellation": false,
  "payAtHotel": false,
  "sortBy": "recommended",
  "currency": "USD",
  "includeDetails": false,
  "maxItems": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call dataspryva/trip-com-hotel-search-and-nightly-price-finder --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/trip-com-hotel-search-and-nightly-price-finder"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/eT4LscLDfutKSxvXg/builds/YqKtYaAlxzHXQ8eZm/openapi.json