Endpoints by data type
Advertiser ads API
2 endpoints on 2 platforms return advertiser ads as the same Ad object. The ads one advertiser has in a public ad library, a page at a time: format, copy, creative, landing page, and when each was first and last shown. A call costs $0.004, each endpoint at its own price; a failed call is free.
Advertiser ads · on each platform
| Platform | Endpoint | Path | A page | Price |
|---|---|---|---|---|
| Meta Ad Library | Meta advertiser ads | GET /v1/meta/advertisers/ads/list | 30 | $0.004 per call · about 30 ads per page |
| Google Ads Transparency | Google advertiser ads | GET /v1/google/advertisers/ads/list | 40 | $0.004 per call · about 40 ads per page |
$0.004 a call, each endpoint at its own price. A call that fails costs nothing.
The object it returns: Ad
Every endpoint above returns these fields with the same names and types. A field a platform does not show comes back null and is named in meta.unavailable.
| Field | Type | Meaning |
|---|---|---|
id | string | Ad ID in the library. |
url | string | Link to the ad in the library. |
advertiser | AdvertiserRef | Who runs the ad. |
title | string | null | Headline, where the ad has one. |
text | string | Ad copy as plain text; empty when the ad has none. |
format | string | null | Creative format; dynamic means the platform assembles it per viewer (catalog ads). |
images | string[] | null | Image URLs of the creative. |
videos | string[] | null | Video URLs of the creative. |
landing_url | string | null | Where the ad leads. |
cta | string | null | Call-to-action button text. |
platforms | string[] | null | Where it is delivered, e.g. facebook, instagram. |
active | boolean | null | Whether the ad is still running. |
first_shown_at | string | null | First time or day shown, ISO 8601 in UTC. |
last_shown_at | string | null | Last time or day shown, ISO 8601 in UTC. |
reach | string | null | People reached, as the library publishes it: a bracket such as 1K-10K, or a count (the EU reach of a Meta ad); null where none is published. |
ext | object | Platform-specific extras. Only returned with view=full. |
The same call on two platforms
Same parameters, same paging, same response shape. Only the path changes.
# Meta Ad Library
curl -G "https://api.okdata.online/v1/meta/advertisers/ads/list" \
-H "Authorization: Bearer $OKDATA_API_KEY" \
--data-urlencode 'id=30147264485'
# Google Ads Transparency
curl -G "https://api.okdata.online/v1/google/advertisers/ads/list" \
-H "Authorization: Bearer $OKDATA_API_KEY" \
--data-urlencode 'id=AR17172796163137470465'What people use it for
- See every ad a competitor runs before you plan your own campaign.
- Check every week which new creatives a brand has started.
- Count how many ads a brand runs on each placement.
Questions
- What do I need to identify the advertiser?
- Google takes the advertiser ID or the brand’s website domain; Meta takes the Facebook page ID or the brand’s name. Each endpoint page lists its parameters.
- Can I tell running ads from stopped ones?
- Each ad carries its first and last shown dates, and active where the library says it. Compare last_shown_at with today to separate the two.
- How do I spot new ads?
- Store the ad ids from each check. Any id you have not seen before is new. A check costs one call per page you read.