> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Recherche de publicités
> Trouvez les publicités diffusées par une entreprise sur LinkedIn, Meta, Google, TikTok et Apple — par source, format, pays cible, portée et période active — et consultez la création, la page de destination et les données d'impressions de chacune.
[Advertisement Search](/fr/api-reference/endpoint/companies/advertisements_search) renvoie les publicités individuelles que Pubrio a capturées, une ligne par publicité. Chaque ligne contient la création (titre, image ou vidéo, page de destination), l'endroit où elle a été diffusée, la période durant laquelle elle a tourné, et la fourchette d'impressions rapportée par la source.
```bash theme={null}
curl -X POST https://api.pubrio.com/companies/advertisements/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domains": ["stripe.com"],
"source_types": ["linkedin", "facebook"],
"active_dates": ["2026-08-01", "2026-08-31"],
"per_page": 25
}'
```
## Quand l'utiliser
* **Veille créative concurrentielle** — ce qu'un concurrent communique, dans quels pays, sous quel format.
* **Intention** — une entreprise qui vient de commencer à faire de la publicité sur un nouveau marché est en train de s'y développer. Combinez avec `target_locations`.
* **Indicateurs de dépense** — `reach_tiers` et les filtres de métriques `advertisement_*` classent les entreprises par volume publicitaire sans donner de chiffre de dépense.
Pour des totaux et des tendances, utilisez [Advertisement Insights](/fr/api-reference/endpoint/companies/advertisements_insights). Pour trouver des *entreprises* à partir de leur activité publicitaire plutôt que les publicités elles-mêmes, utilisez les filtres `advertisement_*` sur [Company Search](/fr/api-reference/endpoint/companies/search).
## Sources
| `source_type` | Remarques |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `linkedin` | Libellés de format riches (`Single Image Ad`, `Document Ad`, …) |
| `facebook` | Couvre Facebook, Instagram, Messenger, Threads et Audience Network ; affinez avec `publisher_platforms`. `meta` est accepté comme alias. |
| `google` | Principalement `text` |
| `tiktok` | |
| `apple` | |
`total_impressions` vaut `null` pour les publicités dont la source ne publie aucune estimation, et ces publicités ne correspondent jamais à `reach_tiers`.
## Cibler une entreprise
| Clé | Valeur |
| --------------- | --------------------------------------------- |
| `domains` | `["stripe.com"]` |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` |
| `companies` | `["5378845d-…"]` — valeurs `domain_search_id` |
Une recherche sans entreprise est autorisée, par exemple `{"target_locations": ["SG"], "source_types": ["linkedin"]}`. Seules les publicités déjà liées à une entreprise Pubrio sont renvoyées, sauf si vous définissez `is_include_unlinked_companies: true`.
## Filtres
### Source et format
| Clé | Type | Correspond à |
| ----------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_types` | `string[]` | `linkedin`, `facebook`, `google`, `tiktok`, `apple`. N'importe laquelle des valeurs listées. Les valeurs inconnues ne correspondent à rien et sont renvoyées dans `metadata.unsupported_source_types`. |
| `exclude_source_types` | `string[]` | Même vocabulaire, exclu. |
| `advertisement_formats` | `string[]` | Formats canoniques : `image`, `video`, `text`, `carousel`, `dynamic_product`, `document`, `message`, `event`, `article`, `spotlight`, `follow`, `job`, `engagement`. Voir [Formats](/fr/api-reference/enums#formats). |
| `publisher_platforms` / `exclude_publisher_platforms` | `string[]` | `facebook`, `instagram`, `messenger`, `threads`, `audience_network`. Uniquement pour les publicités Meta. |
### Texte
| Clé | Type | Correspond à |
| ------------------------------ | --------------------- | ------------------------------------------------------- |
| `headlines` | `string[]` | Texte du titre, n'importe laquelle des valeurs listées. |
| `search_term` / `search_terms` | `string` / `string[]` | Titre et description. |
### Dates
| Clé | Type | Correspond à |
| -------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active_dates` | `[from, to]` | Publicités **actives à un moment quelconque** de la période, y compris celles qui ont démarré plus tôt et sont toujours en ligne. C'est la période utilisée par Advertisement Insights. Les publicités sans `started_at` sont comptées à partir de `created_at`. Les deux dates sont requises ; limites de journée en UTC. |
| `start_dates` | `[from, to]` | `started_at` compris dans la période — publicités *lancées* à ce moment-là. Limites de journée dans le fuseau horaire de l'espace de travail. |
| `end_dates` | `[from, to]` | `ended_at` compris dans la période. Limites de journée dans le fuseau horaire de l'espace de travail. |
| `created_at` | date ou horodatage ISO | Capturé par Pubrio à partir de cet instant (UTC), pour la synchronisation incrémentale. |
`start_dates` masque la plupart des campagnes en cours d'une entreprise, car une campagne lancée en mars est encore active en août. Privilégiez `active_dates`, sauf si vous cherchez spécifiquement des lancements.
### Lieu de diffusion
| Clé | Type | Correspond à |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target_locations` | `string[]` | Pays dans lesquels la publicité a été diffusée. OR par défaut ; ajoutez `{"key": "target_locations", "operator": "and"}` à `filter_conditions` pour exiger tous les pays. |
| `exclude_target_locations` | `string[]` | Pays à exclure. |
| `company_locations` | `string[]` | Pays du siège social de l'annonceur. |
### Portée et volume
| Clé | Type | Correspond à |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reach_tiers` | `string[]` | Tranche d'impressions de la publicité : `lt_1k`, `1k_10k`, `10k_50k`, `50k_100k`, `100k_500k`, `500k_1m`, `1m_plus`. Les publicités sans valeur `total_impressions` ne correspondent jamais. |
| `advertisement_active_ads`, `advertisement_running_ads`, `advertisement_total_ads`, `advertisement_platform_count`, `advertisement_format_count`, `advertisement_impressions_estimate` | `[min, max]` | Filtrez les publicités selon les totaux de **l'annonceur**, par exemple `advertisement_active_ads: [10, null]` renvoie les publicités d'entreprises ayant au moins dix publicités actives. |
| `advertisement_country_activity` | objet | `{ "country": "US", "rank": [null, 100] }` — publicités des 100 premiers annonceurs de ce pays. |
### Enrichissement
| Clé | Type | Remarques |
| ------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `is_realtime_enrichment` | `boolean` | Si la recherche ne renvoie rien, scrape les sources immédiatement puis relance la recherche. Uniquement pour les recherches ciblées sur une entreprise. |
| `enrichment_mode` | `default` / `latest` | `latest` relance un scrape à chaque appel, indépendamment du cache. |
| `is_include_unlinked_companies` | `boolean` | Renvoie aussi les publicités que Pubrio n'a pas pu lier à une fiche entreprise (`is_company_matched: false`). |
### Pagination et ordre
`per_page`, `page` et `is_ascending_order` se comportent comme pour toute recherche. Les lignes sont ordonnées par `created_at` (date de capture), les plus récentes en premier.
## À quoi ressemble une ligne
```json theme={null}
{
"advertisement_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
"advertisement_search_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
"created_at": "2026-09-01T02:00:07.068Z",
"last_modified": "2026-09-01T02:00:07.068Z",
"started_at": "2026-08-24T00:00:00.000Z",
"ended_at": "2026-08-31T00:00:00.000Z",
"title": "Your 2026 peak season prep checklist is here",
"source_type": "linkedin",
"advertisement_format": "Single Image Ad",
"advertisement_format_normalized": "image",
"is_company_matched": true,
"advertiser": "Stripe",
"advertiser_url": "https://www.linkedin.com/company/2135371",
"advertisement_url": "https://www.linkedin.com/ad-library/detail/1518455034",
"total_impressions": "< 1k",
"total_impressions_lower": null,
"total_impressions_upper": 1000,
"image_url": "https://buckets.pubrio.com/images/public/….jpg",
"video_url": null,
"carousel_images": null,
"destination_url": "https://stripe.com/industries/retail?trk=…",
"raw_link_url": null,
"target_country_codes": ["US"],
"publisher_platforms": null,
"companies": {
"domain_search_id": "5378845d-7726-4817-aba9-ced8c5f41dee",
"company_name": "Stripe",
"domain": "stripe.com",
"country_code": "US",
"…": "…"
}
}
```
* `ended_at` vaut `null` tant que la publicité est encore active.
* `advertisement_format` est le libellé propre à la source ; `advertisement_format_normalized` est le slug sur lequel vous pouvez filtrer.
* `destination_url` est la page de destination dépliée ; `raw_link_url` conserve le lien de suivi tel qu'il a été capturé.
* `total_impressions` est le texte de la source ; la paire `_lower` / `_upper` est la fourchette analysée.
### `metadata` sur ce endpoint
```json theme={null}
"metadata": {
"profile": null,
"filters": { "domains": ["stripe.com"], "source_types": ["tiktok", "bogus"], "per_page": 25, "language": "en" },
"ignored_fields": [],
"applied_source_types": ["tiktok"],
"unsupported_source_types": ["bogus"],
"coverage_notes": [{ "source_type": "tiktok", "scope": "eea_uk_ch" }]
}
```
| Clé | Présente quand | Signification |
| -------------------------- | ----------------------- | --------------------------------------------------------------------------------------------- |
| `ignored_fields` | Toujours | Clés du corps de la requête que le endpoint a ignorées |
| `applied_source_types` | `source_types` envoyé | Valeurs qui ont été reconnues |
| `unsupported_source_types` | Valeur inconnue envoyée | Ces valeurs ne correspondaient à rien |
| `coverage_notes` | Le cas échéant | Notes de couverture pour les sources demandées |
| `skipped_source_types` | Le cas échéant | `[{ "source_type", "reason" }]` — sources non appliquées pour les `target_locations` demandés |
## Recettes
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/advertisements/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domains": ["adyen.com", "checkout.com"],
"target_locations": ["SG", "AU"],
"advertisement_formats": ["video", "carousel"],
"active_dates": ["2026-08-01", "2026-09-04"],
"per_page": 25
}'
```
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/advertisements/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"target_locations": ["US"],
"source_types": ["linkedin"],
"reach_tiers": ["100k_500k", "500k_1m", "1m_plus"],
"active_dates": ["2026-08-01", "2026-09-04"],
"per_page": 25
}'
```
Le `companies.domain_search_id` de chaque ligne est une entreprise qui dépense fortement sur LinkedIn aux États-Unis ce mois-ci.
```bash cURL theme={null}
curl -X POST https://api.pubrio.com/companies/advertisements/search \
-H "pubrio-api-key: $PUBRIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domains": ["nike.com"],
"source_types": ["facebook"],
"publisher_platforms": ["instagram"],
"exclude_publisher_platforms": ["facebook"],
"per_page": 25
}'
```
## Voir aussi
Tous les paramètres et champs de réponse.
Totaux, tranches de portée et créations pour une entreprise sur une période.
Trouvez des entreprises à partir de leur activité publicitaire sur Company Search.
Sources, formats, plateformes et tranches de portée.