# Amazon EU Ad Repository Scraper — DSA Ads, Creatives & Reach (`xyrelith-data/amazon-ad-library`) Actor

Query Amazon's EU Digital Services Act ad repository across nine storefronts: keyword or ad-id lookup, restricted-ad browse, advertiser and payer filters, per-country reach bands and creatives saved to storage.

- **URL**: https://apify.com/xyrelith-data/amazon-ad-library.md
- **Developed by:** [Xyrelith Data](https://apify.com/xyrelith-data) (community)
- **Categories:** Automation, E-commerce, Developer tools
- **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

## Amazon EU Ad Repository Scraper — DSA Ads, Creatives & Reach

Amazon publishes a public ad repository for its European Union stores under the Digital Services Act. This actor turns that repository into structured rows: search by brand, advertiser, creator, product or content words; look up exact ad ids; or browse the restricted-ads catalogue. Every row carries the advertiser and payer, first and last delivery days, targeting methods, reach bands per country and Amazon store, landing pages, creatives and moderation details. No login, cookies, API key or proxy setup.

### What this actor does

- **Three modes:** keyword/browse `search`, exact `byAdIds` lookup, and `removedAds` for the compliance catalogue.
- **Nine EU storefronts:** amazon.de, .fr, .it, .es, .nl, .pl, .se, .com.be and .ie — one EU-wide repository, with a true country filter.
- **Advertiser, payer and ASIN filters:** keep only the names or products you care about; exact or contains matching for names.
- **Content controls:** sponsored ads, affiliate/influencer content, or both; restricted ads excluded, merged, or only.
- **Per-country reach:** total impressions band plus the full country/store breakdown Amazon publishes.
- **Creatives kept alive:** image, video and audio files are saved to the run's key-value store and emitted as stable links; media types are still reported when files are skipped.
- **Empty fields are omitted** — no `null`, blank strings or empty lists in the dataset.

### Output per ad

Identity and source:

- `adId`, `adUrl`, `sourceUrl` — Amazon's id and the ad's detail page
- `type` — `AD` or `AFFILIATE_MARKETING_CONTENT`; `contentType` — `ad` or `affiliateMarketingContent`
- `recordType: "ad"`, `scrapedAt`

Advertiser and timing:

- `advertiserName`, `payerName`, `payerDiffers`
- `advertisementPurpose`, `advertisementPurposes[]` — Amazon's ad text/title, split on the source separator
- `firstShown`, `lastShown` — first/last delivery day (UTC, `YYYY-MM-DD`)
- `daysShown`, `daysSinceLastShown`

Targeting and reach:

- `targetingMethods[]`, `targetingDetails[]` — method code plus a plain-language description for the known methods
- `impressionsMin`, `impressionsMax`, `impressionsText` — total recipients band
- `reachBySite` — Amazon's `country → {min,max}` map
- `recipientsBreakdown[]` — `amazonSite`, `countryCode`, `{min,max}` rows
- `countries[]`, `amazonSites[]` — sorted codes seen in the breakdown

Content and creatives:

- `subjectMatterUrl` — the affiliate content page when Amazon provides one
- `landingPages[]`, `destinationUrl` — product, brand-store and other linked pages
- `asin`, `productUrl`, `productStore`, `brandStoreUrl` — derived only from a real product/store URL
- `creativeList[]` — `{mediaType, linkedPage, mediaUrl, mediaUrlOriginal, mediaExpiresAt, mediaSizeBytes, mediaDownloadStatus}`
- `mediaUrls[]`, `mediaTypes[]`, `hasMedia`

Moderation and traceability:

- `isRestricted`, `restrictionCategory`, `restrictionCategories[]`
- `restrictionDetectionAutomated`, `illegalContentReport`
- `marketplace`, `query`, `foundVia` — where the row came from

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` / `byAdIds` / `removedAds` |
| `searchTerms` | array | `[]` | Brand, advertiser, creator, product or content words (mode=search). Empty = browse all in the window. |
| `adIds` | array | `[]` | Amazon ad ids or detail URLs (mode=byAdIds). |
| `country` | string | `All` | `All` or an exact country: Belgium, France, Germany, Italy, Netherlands, Poland, Spain, Sweden, Ireland. |
| `marketplace` | string | `amazon.de` | Storefront used for requests and detail links; all nine serve the same EU dataset. |
| `dateRange` | string | `last30days` | `last7days`, `last30days`, `last90days`, `last12months`, `custom`, `all`. |
| `startDate` | string | – | `YYYY-MM-DD`, used with `dateRange=custom`. |
| `endDate` | string | – | `YYYY-MM-DD`, used with `dateRange=custom`. |
| `restrictedAds` | string | `exclude` | `exclude`, `include` (after normal results) or `only`. |
| `contentType` | string | `all` | `all`, `ad` or `affiliate`. |
| `advertiserNames` | array | `[]` | Keep rows whose advertiser matches any name. |
| `payerNames` | array | `[]` | Keep rows whose payer matches any name. |
| `nameMatchType` | string | `contains` | `contains` or `exact` (case/punctuation-insensitive). |
| `asins` | array | `[]` | Keep rows whose landing page contains one of these ASINs or product URLs. |
| `mediaOnly` | boolean | `false` | Keep only ads with an image, video or audio creative. |
| `mediaMode` | string | `download` | `download` saves creatives to the key-value store; `none` reports media types only. |
| `maxMediaMb` | integer | `50` | Skip larger creative files; `0` disables downloads. |
| `maxMediaFiles` | integer | `100` | Cap files saved per run; `0` disables downloads. |
| `maxItems` | integer | `100` | Hard cap on emitted rows. |
| `maxItemsPerSearch` | integer | `0` | Cap per search term; `0` = global cap only. |
| `maxPagesPerSearch` | integer | `100` | 50 ads per page; lower it to limit requests. |

#### Example: competitor watch in Germany

```json
{
  "mode": "search",
  "searchTerms": ["Nivea", "Samsung"],
  "country": "Germany",
  "dateRange": "last90days",
  "advertiserNames": ["Nivea", "Samsung Deutschland"],
  "nameMatchType": "contains",
  "contentType": "ad",
  "mediaMode": "download",
  "maxItems": 200
}
```

#### Example: affiliate and influencer content

```json
{
  "mode": "search",
  "searchTerms": ["beauty", "unboxing"],
  "country": "All",
  "dateRange": "last30days",
  "contentType": "affiliate",
  "maxItems": 100
}
```

#### Example: look up known ads

```json
{
  "mode": "byAdIds",
  "adIds": [
    "9287036812522d737b4a187e271a412cf1a6911e",
    "https://www.amazon.de/adlibrary/detail/4c16025fb8c021c28d9f1886ad719ed34657a4cb"
  ],
  "mediaMode": "download",
  "maxItems": 10
}
```

#### Example: removed ads for a period

```json
{
  "mode": "removedAds",
  "country": "France",
  "dateRange": "custom",
  "startDate": "2026-01-01",
  "endDate": "2026-06-30",
  "maxItems": 100
}
```

### Use cases

- **Competitive intelligence** — follow a brand's sponsored products and affiliate creators across EU stores.
- **Retail-media research** — measure how many ads a seller runs and the reach band per country.
- **Creative monitoring** — keep a dated archive of ad images and videos before Amazon's links expire.
- **Compliance and DSA studies** — export removed ads with restriction categories and detection flags.
- **Lead generation** — find active advertisers and the legal entities paying for their ads.
- **Marketplace analytics** — join ad activity with product/ASIN data for category-level insight.

### FAQ

**Where does the data come from?** Amazon's public ad repository for its EU stores, published under the Digital Services Act. The actor reads the same JSON endpoints the public ad-library page uses, without an account.

**Which countries are covered?** Germany, France, Italy, Spain, the Netherlands, Poland, Sweden, Belgium and Ireland. There is no US or UK ad repository.

**Why does the actor ask for a marketplace if all nine return the same data?** Amazon serves one EU-wide repository from every EU store domain. The marketplace field chooses the domain used for requests and for the `adUrl` in each row; the `country` field is the real filter.

**How fresh is the data?** Amazon updates the repository continuously; new ads appear after they are first shown. The actor reads it live on every run.

**Why can't I search by payer name alone?** Amazon's public endpoint searches ad text and advertiser/creator names, not payer names. The actor can filter payer names on the rows it fetches, but a payer-only search needs an advertiser or product term to seed the result set.

**Why do some ads have no end date, payer, reach or targeting?** Affiliate/influencer content is disclosed differently: it often has only a start date, creator and content link. Restricted ads also withhold advertiser, payer and content. Missing fields are omitted, never invented.

**Why do creative links stop working after the run?** Amazon's media links are signed and expire after about 30 minutes. With `mediaMode=download` the actor saves the file to the run's key-value store and emits a stable link, keeping the signed source as `mediaUrlOriginal` for traceability. With `mediaMode=none` it reports only `hasMedia` and `mediaTypes`.

**Why are some ads missing from a search?** Amazon's search is relevance-ranked and full-text over ad titles and advertiser names. A brand can appear in another seller's product text; use `advertiserNames` with `exact` for only the brand's own rows. Very broad terms can be deep, so set `maxItems` and `maxPagesPerSearch`.

**Can I get a bulk CSV from Amazon?** No. Amazon's public repository has no bulk export endpoint; this actor pages through the same 50-row pages and gives you a dataset you can export as CSV, Excel or JSON from Apify.

**Do I need a proxy or cookies?** No. The actor reads the public repository directly and chooses a working EU storefront automatically.

**Is this affiliated with Amazon?** No. It is a third-party tool that reads Amazon's public transparency data. You are responsible for how you use the data.

# Actor input Schema

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

What to fetch: keyword/browse search, exact ad-id lookup, or the restricted-ads catalogue.

## `searchTerms` (type: `array`):

Brand, advertiser, creator, product or content words (mode=search). Empty = browse all ads in the country/date window. Amazon searches ad text and advertiser names; payer names are not searchable.

## `adIds` (type: `array`):

Amazon ad ids (hex or amzn1.\*) or full ad-library detail URLs.

## `country` (type: `string`):

Only ads delivered in this country (Amazon's location filter). Use All for every EU country.

## `marketplace` (type: `string`):

EU storefront used for requests and detail links. All nine serve the same EU-wide repository; the Country field is the real filter.

## `dateRange` (type: `string`):

Window in which the ad was delivered. Custom uses Start/End; All includes the oldest rows Amazon serves.

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

First delivery day, YYYY-MM-DD. Only used when dateRange=custom.

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

Last delivery day, YYYY-MM-DD. Only used when dateRange=custom.

## `restrictedAds` (type: `string`):

Exclude restricted ads, merge them after normal results, or browse only the restricted catalogue. Amazon has no text search for restricted ads.

## `contentType` (type: `string`):

All rows, sponsored ads only, or affiliate/influencer marketing content only.

## `advertiserNames` (type: `array`):

Keep ads whose advertiser name matches any of these (client-side; match type below). Leave empty for all.

## `payerNames` (type: `array`):

Keep ads whose payer name matches any of these (client-side). Amazon cannot search payers. Leave empty for all.

## `nameMatchType` (type: `string`):

How advertiser and payer names are compared.

## `asins` (type: `array`):

Keep ads whose landing page contains one of these ASINs or product URLs. Leave empty for all.

## `mediaOnly` (type: `boolean`):

Keep only ads that carry an image, video or audio creative.

## `mediaMode` (type: `string`):

Download: save image/video/audio files to this run's key-value store and emit public links. None: report media types only, no URLs.

## `maxMediaMb` (type: `integer`):

Skip larger creative files. 0 disables media downloads.

## `maxMediaFiles` (type: `integer`):

Cap creative files saved in one run. 0 disables media downloads.

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

Hard cap on emitted ad records for the whole run.

## `maxItemsPerSearch` (type: `integer`):

Cap per search term. 0 = only the global Max items cap applies.

## `maxPagesPerSearch` (type: `integer`):

50 ads per page. Lower it to limit requests; 0 is not allowed.

## Actor input object example

```json
{
  "mode": "search",
  "searchTerms": [],
  "adIds": [],
  "country": "Germany",
  "marketplace": "amazon.de",
  "dateRange": "all",
  "restrictedAds": "exclude",
  "contentType": "all",
  "advertiserNames": [],
  "payerNames": [],
  "nameMatchType": "contains",
  "asins": [],
  "mediaOnly": false,
  "mediaMode": "none",
  "maxMediaMb": 50,
  "maxMediaFiles": 0,
  "maxItems": 1,
  "maxItemsPerSearch": 0,
  "maxPagesPerSearch": 1
}
```

# Actor output Schema

## `ads` (type: `string`):

Dataset containing every scraped Amazon EU ad or affiliate content record.

# 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": "search",
    "searchTerms": [],
    "adIds": [],
    "country": "Germany",
    "marketplace": "amazon.de",
    "dateRange": "all",
    "restrictedAds": "exclude",
    "contentType": "all",
    "advertiserNames": [],
    "payerNames": [],
    "nameMatchType": "contains",
    "asins": [],
    "mediaOnly": false,
    "mediaMode": "none",
    "maxMediaMb": 50,
    "maxMediaFiles": 0,
    "maxItems": 1,
    "maxItemsPerSearch": 0,
    "maxPagesPerSearch": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("xyrelith-data/amazon-ad-library").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": "search",
    "searchTerms": [],
    "adIds": [],
    "country": "Germany",
    "marketplace": "amazon.de",
    "dateRange": "all",
    "restrictedAds": "exclude",
    "contentType": "all",
    "advertiserNames": [],
    "payerNames": [],
    "nameMatchType": "contains",
    "asins": [],
    "mediaOnly": False,
    "mediaMode": "none",
    "maxMediaMb": 50,
    "maxMediaFiles": 0,
    "maxItems": 1,
    "maxItemsPerSearch": 0,
    "maxPagesPerSearch": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("xyrelith-data/amazon-ad-library").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": "search",
  "searchTerms": [],
  "adIds": [],
  "country": "Germany",
  "marketplace": "amazon.de",
  "dateRange": "all",
  "restrictedAds": "exclude",
  "contentType": "all",
  "advertiserNames": [],
  "payerNames": [],
  "nameMatchType": "contains",
  "asins": [],
  "mediaOnly": false,
  "mediaMode": "none",
  "maxMediaMb": 50,
  "maxMediaFiles": 0,
  "maxItems": 1,
  "maxItemsPerSearch": 0,
  "maxPagesPerSearch": 1
}' |
apify call xyrelith-data/amazon-ad-library --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,xyrelith-data/amazon-ad-library"
        }
    }
}
```

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/7RSZNHchQbsOVYB4R/builds/FdFTa2mSzKP30FZG1/openapi.json
