# Booking.com Ads Repository Scraper — Hotel Ads Library (DSA) (`rastriq/booking-ads-repository-scraper`) Actor

Scrape the Booking.com Ads Repository (EEA, DSA): advertised property, who paid (hotel chain, OTA, channel manager), first and last date shown, targeting type and impressions per country. Splits long periods automatically.

- **URL**: https://apify.com/rastriq/booking-ads-repository-scraper.md
- **Developed by:** [Rastriq — Structured data from the world](https://apify.com/rastriq) (community)
- **Categories:** Travel
- **Features:** Limited permissions
- **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

## Booking.com Ads Repository Scraper — Hotel Ads Library (DSA)

**Booking.com Ads Repository Scraper** extracts ads from the official [Booking.com Ads Repository](https://www.booking.com/ad-repository.html), the EEA ad library Booking.com publishes under the Digital Services Act: the advertised property, the hotel chain, OTA or channel manager that paid, first and last date shown, targeting type and impressions — total and per country. Use it as a Booking.com ads API for hospitality competitor research, distribution analysis and DSA transparency work.

### 🔎 What is Booking.com Ads Repository Scraper?

Booking.com's repository page shows 20 ads at a time and its backend refuses long date ranges. **Booking.com Ads Repository Scraper** turns it into structured data:

- 💳 **Search by who paid** — `Wyndham`, `IHG`, `Derbysoft`… (prefix, case-insensitive)
- 🏨 **Search by property** — every ad whose property name starts with `Hilton`, `Ibis`…
- 🌍 **Or the whole repository** — every ad shown in the EEA in your period
- ✂️ **Long periods handled** — when Booking's backend gives up on a range, it is split automatically and merged without duplicates
- 👁️ **Impressions** — total and per EEA country, as Booking's ranges and as numbers (`reach_min`/`reach_max`)
- ✅ **Data quality** — `quality_flags`, DSA art. 39 coverage and natural-person flags

Typical uses: which hotel chains and channel managers buy Booking.com ads, how many properties a group promotes and where, impression benchmarks by country, and research on travel advertising.

### 📦 What data does Booking.com Ads Repository Scraper extract?

Every row has the common block shared by all Rastriq ad-library scrapers plus **every field Booking.com publishes, with Booking.com's original names**.

| Group | Fields |
|---|---|
| 🆔 Identity | `platform`, `ad_id`, `source_url`, `scraped_at` (+ `id`) |
| 🏨 Ad | `advertiser` (+ `adName`: the advertised property) |
| 💳 Paid by | `payer` (+ `legalEntity`) |
| 📅 Period | `first_shown`, `last_shown` (+ `dateStarted`, `dateLastShown`) |
| 👁️ Impressions | `reach_min`, `reach_max`, `reach_by_country`, `countries` (+ `totalViewsBucket`, `viewersPerCountry`) |
| 🎯 Targeting | `targeting_types` (+ `targetingType`) |
| ✅ Quality | `quality_flags[]`, `art39_coverage`, `is_natural_person_suspected` |
| 🔁 Traceability | `query_legal_entity_prefix`, `query_ad_name_prefix`, `query_date_from`, `query_date_to` |

#### 📄 Flat table or nested JSON

By default every row is a **flat table** — one value per column, ready for Excel, Google Sheets or CSV: lists become comma-separated text (URLs are separated by `|`), reach per country becomes `reach_min_<CC>` / `reach_max_<CC>` columns, and the DSA art. 39 score becomes `art39_covered`, `art39_total`, `art39_ratio` and `art39_missing`. Set **Output format** to *Nested JSON* to keep the source's original objects and lists for programmatic use.

### 🚀 How to use Booking.com Ads Repository Scraper

1. Open **Booking.com Ads Repository Scraper** in Apify Console and click **Try for free**.
2. Add **Paid by** names (`Wyndham`) and/or **Ad name** prefixes (`Hilton`), or leave both empty for every ad.
3. Choose the period with **From / To**.
4. Set **Max ads** (100 for a first test) and click **Start**.
5. Export the results as JSON, CSV or Excel, or get them through the API.

### ⚙️ Input parameters

| Parameter | Type | Default | Description |
|---|---|---|---|
| `legalEntities` | array | — | Who paid, matched from the beginning of the name |
| `adNames` | array | — | Advertised property, matched from the beginning |
| `startDate` / `endDate` | string | `30 days` / today | Ads shown in the period |
| `maxItems` | integer | `1000` | Max ads in the run (0 = no limit) |
| `hashPersonalNames` | boolean | `false` | Pseudonymise payers flagged as private individuals |
| `outputFormat` | string | `flat` | `flat` (one column per value) or `nested` (original JSON structure) |

```json
{
  "legalEntities": ["Wyndham", "IHG"],
  "startDate": "2026-01-01",
  "endDate": "2026-06-30",
  "maxItems": 5000
}
```

### 📤 Output example

One row of the default flat output (selected columns):

```json
{
  "platform": "booking",
  "ad_id": "748c06f2-1bc7-4508-a4b3-d315eee72652",
  "advertiser": "Ramada Plaza by Wyndham Orlando Resort & Suites Intl Drive - Newly Renovated!",
  "payer": "Wyndham",
  "first_shown": "2025-02-10",
  "last_shown": "2026-11-10",
  "reach_min": 1000,
  "reach_max": 10000,
  "reach_min_DE": 1000,
  "reach_max_DE": 10000,
  "reach_min_FR": 0,
  "reach_max_FR": 1000,
  "countries": "AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK",
  "targeting_types": "DEFAULT",
  "totalViewsBucket": "1K-10K",
  "source_url": "https://www.booking.com/ad-repository.html",
  "quality_flags": "reach_is_impressions, impressions_updated_quarterly, no_creative_in_source, advertiser_is_property_name, po…",
  "art39_ratio": 0.857,
  "art39_missing": "content",
  "is_natural_person_suspected": false,
  "scraped_at": "2026-11-11T18:31:03Z"
}
```

…plus one `reach_min_<CC>` / `reach_max_<CC>` pair per EEA country and every field Booking.com publishes.

Good to know: Booking.com publishes impressions ("views") as ranges and updates them quarterly (`impressions_updated_quarterly`); everything else is updated daily. The API exposes no creative image or landing URL (`no_creative_in_source`).

### 💰 How much does it cost to scrape the Booking.com Ads Repository?

Booking.com Ads Repository Scraper uses pay-per-event pricing with volume discounts by Apify plan. You pay per ad delivered; ads found again in another window or search are free.

| Apify plan | Price per 1,000 ads | Run start |
|---|---|---|
| Free | $0.40 | $0.002 |
| Starter (Bronze) | $0.35 | $0.002 |
| Scale (Silver) | $0.30 | $0.0015 |
| Business (Gold) | $0.25 | $0.001 |

- **Free plan ($5 credit)**: ~12,000 ads
- **Speed**: ~150–500 ads per minute (20 per request; deep pages of large searches are slower)

> 💡 **Tip**: a month of the whole repository is ~35,000 ads. Start with a payer prefix.

### 🔗 Related Actors

Build a cross-platform view of competitor advertising with the Rastriq ad intelligence suite:

- [Google Ads Transparency Center Scraper](https://apify.com/Rastriq/google-ads-scraper) — Search, YouTube and Display ads
- [Facebook Ad Library Scraper](https://apify.com/Rastriq/fb-adlibrary-scraper) — Meta ads (Facebook & Instagram)
- [TikTok Ad Library Scraper](https://apify.com/Rastriq/tiktok-ad-library-scraper) — TikTok ads, targeting and reach
- [LinkedIn Ad Library Scraper](https://apify.com/Rastriq/linkedin-ad-library-scraper) — B2B ads on LinkedIn
- [X (Twitter) Ads Library Scraper](https://apify.com/Rastriq/x-ads-repository-scraper) — X ads in the EU

All of them share the same base fields (`platform`, `ad_id`, `advertiser`, `payer`, `first_shown`, `reach_by_country`…), so their datasets stack in one table.

### ❓ FAQ

**Which ads are included?** Every ad that received impressions on Booking.com in the EEA, which is what Booking.com publishes under the DSA. Ads stay in the repository for one year after they were last shown. A period returns every ad shown during it, including ads that started earlier.

**How does the search work?** Booking.com matches the **beginning** of the payer's name or of the property name, ignoring case. `Wyndham` finds *Wyndham*; `Hilton` finds *Hilton Garden Inn Paris…*.

**Why are long periods split?** Booking.com's backend gives up on heavy searches (whole repository over ~2 months, or one payer over a year). Booking.com Ads Repository Scraper detects it and splits the period in two, as often as needed, then merges the results. The run summary (`OUTPUT`) lists the windows and splits.

**Does it collect personal data?** The payer can be a private individual. Booking.com Ads Repository Scraper flags those rows with `is_natural_person_suspected` and can pseudonymise the name (`hashPersonalNames`). You are responsible for processing the data lawfully (GDPR).

**Is it legal to scrape the Booking.com Ads Repository?** The Actor uses the API Booking.com documents on the repository page, at a moderate rate. You are responsible for complying with Booking.com's terms and applicable laws in how you use the data.

**Something broke?** Open an issue in the Actor's **Issues** tab — we usually reply within 24 hours.

# Changelog

This Actor's version history is a separate document: https://apify.com/rastriq/booking-ads-repository-scraper/changelog.md

# Actor input Schema

## `legalEntities` (type: `array`):

Legal entity or person that paid for the ad. Booking matches the <b>beginning</b> of the name, case-insensitive: <code>Wyndham</code>, <code>IHG</code>, <code>Derbysoft</code>…

## `adNames` (type: `array`):

Name of the advertised property, matched from the beginning: <code>Hilton</code> finds <i>Hilton Garden Inn…</i>, <i>Hilton Paris Opera</i>…

## `startDate` (type: `string`):

Ads <b>shown at any time</b> in the period, including ads that started earlier. Absolute (<code>2026-01-01</code>) or relative (<code>30 days</code>).

## `endDate` (type: `string`):

End of the period. Empty = today.

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

Maximum ads in the dataset for the whole run. 0 = no limit.

## `outputFormat` (type: `string`):

<b>Flat</b> (default): every value in its own column — lists become comma-separated text, reach per country becomes <code>reach_min_DE</code> / <code>reach_max_DE</code> columns, and art. 39 coverage becomes <code>art39_ratio</code> / <code>art39_missing</code>.<br><br><b>Nested</b>: keeps the source's original objects and lists (e.g. the full per-language variations or per-country breakdown) for programmatic use.

## `hashPersonalNames` (type: `boolean`):

The payer can be a private individual. Rows are always flagged <code>is_natural_person_suspected</code>; turn this on to replace those names with a stable SHA-256 pseudonym.

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

Not needed normally.

## `intervalSec` (type: `integer`):

Pause between requests to Booking (randomised ±15 %).

## `maxRetries` (type: `integer`):

Retries for temporary errors (429/5xx) with exponential backoff.

## Actor input object example

```json
{
  "legalEntities": [
    "Wyndham"
  ],
  "startDate": "7 days",
  "maxItems": 100,
  "outputFormat": "flat",
  "hashPersonalNames": false,
  "intervalSec": 2,
  "maxRetries": 4
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

## `reach` (type: `string`):

No description

## `compliance` (type: `string`):

No description

## `allFields` (type: `string`):

No description

## `runSummary` (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 = {
    "legalEntities": [
        "Wyndham"
    ],
    "startDate": "7 days",
    "maxItems": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("rastriq/booking-ads-repository-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 = {
    "legalEntities": ["Wyndham"],
    "startDate": "7 days",
    "maxItems": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("rastriq/booking-ads-repository-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 '{
  "legalEntities": [
    "Wyndham"
  ],
  "startDate": "7 days",
  "maxItems": 100
}' |
apify call rastriq/booking-ads-repository-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rastriq/booking-ads-repository-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/vv6NOw8VDLOKwAP70/builds/r3asheZtvScBoZiFl/openapi.json
