# Agoda Hotels Scraper (`tidyharvest/agoda-hotels-scraper`) Actor

Agoda hotels by city or by URL: search a destination for every hotel with prices, or get full details and every room rate for your dates, price calendar, any currency. From $2.20 per 1,000 listings.

- **URL**: https://apify.com/tidyharvest/agoda-hotels-scraper.md
- **Developed by:** [TidyHarvest](https://apify.com/tidyharvest) (community)
- **Categories:** Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
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

## Agoda Hotels Scraper

Get any **Agoda hotel** as one clean row: address and map position, star rating, guest scores with sub-scores, facilities, policies, photos, room types, and **every bookable room rate for your dates** (price per night, total, cancellation terms, breakfast, taxes). Give it **a city to search** (every hotel there with its cheapest price, sorted the way you want), or hotel URLs, hotel IDs or hotel names. Add a check-in date for live prices, or a whole **range of dates for a price calendar**, in any of 29 currencies.

Built to compete with Fast Agoda Scraper, Agoda Scraper by bovi and Agoda Hotel & Room Scraper: **destination search, full hotel details, every room rate and a multi-date price calendar in one actor**. City search results cost **from $2.20 per 1,000 hotels**; full hotel records **from $3.80 per 1,000** (bovi $5.00; Fast Agoda Scraper $6.00 plus a $0.02 start fee per run).

### What you can do with it

- **Track rates:** price the same hotels every week for the next 3 months and watch them move.
- **Rate parity checks:** see Agoda's price for each hotel and room type, with and without taxes, and the cancellation terms.
- **Build hotel datasets:** address, coordinates, stars, scores, facilities and photos for a list of hotels.
- **Map a market:** list every hotel in a city with stars, score, area, coordinates and tonight's cheapest price, then sort by price or score.
- **Compare markets:** pick the country the visitor is in; Agoda changes the price by market.

### Input

| Field | What it does |
|---|---|
| `destinations` | One city per line (for example `Lisbon`). Returns the city's hotels with the cheapest price for the stay. |
| `sortBy`, `maxHotelsPerDestination`, `minReviewScore`, `minStars` | Order, how many, and quality filters for a destination search. |
| `includeDetails` | For a destination search: add the full record and every room rate for each hotel found. |
| `hotelUrls` | One hotel per line: Agoda page URL, numeric hotel ID, or hotel name. `matchesPerName` uses several matches for a name. |
| `checkIn`, `nights` | The stay to price. Leave `checkIn` empty for details only. |
| `checkInDates`, `checkInFrom` + `checkInTo` + `stepDays` | More check-in dates: one row per hotel per date. |
| `adults`, `children`, `childAges`, `rooms` | Who is staying. |
| `currency` | Show prices in this currency (converted at the day's European Central Bank rate, shown in each row). Default USD. |
| `market` | Country the visitor is in (Agoda prices differ by market). |
| `onlyAvailable`, `maxPricePerNight`, `minStars` | Skip hotels that do not fit. |
| `includeRoomTypes`, `includePhotos` | Leave out parts you do not need. |
| `maxItems` | Cap on rows (and cost). |

Examples:

```json
{ "destinations": ["Lisbon"], "checkIn": "2027-01-15", "nights": 2, "sortBy": "price_low_to_high", "maxHotelsPerDestination": 200 }
```

```json
{ "hotelUrls": ["49487", "The Peninsula Bangkok"], "checkInFrom": "2027-01-10", "checkInTo": "2027-01-31", "stepDays": 7, "nights": 2, "currency": "EUR" }
```

### Output

A destination search gives one light row per hotel: `hotelId`, `name`, `url`, `starRating`, `area`, `city`, `country`, `latitude`, `longitude`, `reviewScore`, `reviewCount`, `available`, `pricePerNight`, `pricePerNightWithTaxes`, `totalPrice`, `currency`, `searchRank`. Hotel lookups (and destination searches with full details) give one full row per hotel and check-in date. Main fields: `hotelId`, `name`, `url`, `starRating`, `address`, `city`, `country`, `latitude`, `longitude`, `reviewScore`, `reviewCount`, `categoryScores`, `scoreDistribution`, `description`, `checkInFrom`, `checkOutUntil`, `facilities`, `policies`, `nearby`, `photos`, `roomTypes`, and for a priced stay `stay`, `available`, `lowestPricePerNight`, `lowestPriceTotal` and `rates`:

```json
{ "roomName": "Room with 1 double bed", "pricePerNight": 182.68, "pricePerNightWithTaxes": 198.53, "totalPrice": 397.05, "currency": "USD",
  "nights": 2, "breakfastIncluded": false, "freeCancellation": false, "cancellationPolicy": "Non-refundable (Low price!)",
  "taxesAndFees": ["Tax 5%", "City Tax (Pay at the property) 4%"], "benefits": ["Free WiFi"], "maxOccupancy": 3 }
```

### Pricing

Pay per row: **from $2.20 per 1,000 search listings** (`listing-scraped`; $3.00 on the Free plan) and **from $3.80 per 1,000 full hotel records** (`hotel-scraped`; $5.00 on the Free plan). No start fee. Caps and filters apply before you are charged. A run that finds nothing fails instead of returning an empty dataset.

### Limits and notes

- Destination search covers cities; areas, landmarks and map-radius searches are not included.
- Agoda shows about 2,000-4,000 hotels for a big city; a destination search can read them all (about 45 per request).
- Agoda lists only rooms that are free for the dates; sold-out room types are not shown.
- Non-USD prices are converted from Agoda's US-dollar quote at the European Central Bank rate (the rate and date are in each row).
- Public pages only; no login. Check the terms that apply to your use of the data.

### Feedback and requests

We welcome feedback: a field or option you wish this had, a change to how it works, or a scraper you would like us to build.
Open an issue in the **Issues** tab of this page and tell us what you need. We read every one, and we build the requests that
come up most. If this actor works well for you, a short review helps other people find it.

# Actor input Schema

## `hotelUrls` (type: `array`):

One Agoda hotel per line: page URL, numeric hotel ID, or hotel name. Leave empty if you only search destinations.

## `matchesPerName` (type: `integer`):

When a line is a hotel name, how many matching hotels to use (best matches first). 1 = just the top match.

## `destinations` (type: `array`):

One city per line, for example Bangkok or Lisbon, Portugal (or city:10647 with an Agoda city ID). Returns the city's hotels with the cheapest price for your stay. No check-in date given = priced for a stay 14 days from now.

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

Order of the hotels in a destination search.

## `maxHotelsPerDestination` (type: `integer`):

Cap for each city and each check-in date (45 hotels per page of results).

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

Off: one light row per hotel (name, stars, area, score, price). On: the full hotel record with all room rates, billed as a full hotel row.

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

Add a stay to get live room prices. Leave empty for hotel details only (no prices).

## `nights` (type: `integer`):

Length of stay (1-30).

## `minReviewScore` (type: `number`):

Skip hotels scoring lower.

## `checkInDates` (type: `array`):

Extra check-in dates, YYYY-MM-DD, one per line. Each hotel gets one row per date, so you can track prices across dates.

## `checkInFrom` (type: `string`):

With 'to', prices every check-in date in the range.

## `checkInTo` (type: `string`):

Last check-in date of the range.

## `stepDays` (type: `integer`):

Days between check-in dates in the range (7 = weekly).

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

Adults per room.

## `children` (type: `integer`):

Number of children.

## `childAges` (type: `array`):

One age per child, one per line (needed for exact family pricing).

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

Number of rooms.

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

Agoda quotes in US dollars; other currencies are converted at the day's European Central Bank rate (the rate is added to each row).

## `market` (type: `string`):

Agoda shows prices in the currency of the visitor's country, and the price can differ by market. Pick a country to get the prices (and currency) a visitor from there would see.

## `includeRoomTypes` (type: `boolean`):

Room type list with size, beds, occupancy and amenities.

## `includePhotos` (type: `boolean`):

Hotel photo URLs.

## `onlyAvailable` (type: `boolean`):

Skip hotel rows that have no bookable room for the stay.

## `maxPricePerNight` (type: `number`):

Skip hotels whose cheapest rate per night is above this (in the chosen currency). Needs a check-in date.

## `minStars` (type: `number`):

Skip hotels with fewer stars.

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

Hard cap on rows for the whole run (also caps your cost). 0 or empty = no limit.

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

Agoda refuses most cloud IPs, so the default is Apify proxy (datacenter first, residential only if that is blocked).

## Actor input object example

```json
{
  "hotelUrls": [
    "https://www.agoda.com/ibis-budapest-city/hotel/budapest-hu.html"
  ],
  "matchesPerName": 1,
  "destinations": [],
  "sortBy": "recommended",
  "maxHotelsPerDestination": 50,
  "includeDetails": false,
  "nights": 1,
  "stepDays": 1,
  "adults": 2,
  "children": 0,
  "rooms": 1,
  "currency": "USD",
  "market": "",
  "includeRoomTypes": true,
  "includePhotos": true,
  "onlyAvailable": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `hotels` (type: `string`):

One item per hotel.

# 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 = {
    "hotelUrls": [
        "https://www.agoda.com/ibis-budapest-city/hotel/budapest-hu.html"
    ],
    "destinations": [],
    "maxHotelsPerDestination": 50,
    "checkIn": "",
    "checkInFrom": "",
    "checkInTo": "",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("tidyharvest/agoda-hotels-scraper").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 = {
    "hotelUrls": ["https://www.agoda.com/ibis-budapest-city/hotel/budapest-hu.html"],
    "destinations": [],
    "maxHotelsPerDestination": 50,
    "checkIn": "",
    "checkInFrom": "",
    "checkInTo": "",
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("tidyharvest/agoda-hotels-scraper").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 '{
  "hotelUrls": [
    "https://www.agoda.com/ibis-budapest-city/hotel/budapest-hu.html"
  ],
  "destinations": [],
  "maxHotelsPerDestination": 50,
  "checkIn": "",
  "checkInFrom": "",
  "checkInTo": "",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call tidyharvest/agoda-hotels-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tidyharvest/agoda-hotels-scraper"
        }
    }
}
```

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/xfDs1EUrrBdqi11cz/builds/yvTxIGlRaAwzaqKX7/openapi.json