Advertiser Statistics API
Query weekly advertiser statistics from Google Ads transparency data.
Endpoint
GET /api/v1/ads-statistics?action=advertiserStatistics&advertiserId=39687&startDay=2026-03-01&endDay=2026-03-31Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
action | string | Yes | Fixed value: advertiserStatistics |
advertiserId | number | Yes | Plain advertiser ID |
startDay | string | Yes | Date in YYYY-MM-DD; the selected range can cover at most 8 Google Ads weekly buckets |
endDay | string | Yes | Date in YYYY-MM-DD; the selected range can cover at most 8 Google Ads weekly buckets |
Limits
startDayandendDaycan cover at most 8 Google Ads weekly buckets: days 1-7, 8-14, 15-21, and 22-end of each month.- The response contains active weekly rows only. Zero-count host/week rows are omitted.
- If the selected range still produces more than 20,000 active weekly rows, the API returns an error. Narrow the date range and retry.
Example
GET /api/v1/ads-statistics?action=advertiserStatistics&advertiserId=39687&startDay=2026-03-01&endDay=2026-03-31
Authorization: Bearer YOUR_API_KEYResponse Example
{
"code": "ok",
"message": "ok",
"data": {
"endpoint": "ads-statistics",
"action": "advertiserStatistics",
"costCredits": 3,
"remainingCredits": 97,
"query": {
"action": "advertiserStatistics",
"advertiserId": "39687",
"startDay": "2026-03-01",
"endDay": "2026-03-31"
},
"result": {
"adsAdvertiser": {
"advertiser": "ai.law",
"country": "US",
"countryName": "United States",
"id": 39687
},
"hostWeekStatistics": [
{
"adCount": 8,
"host": {
"domain": "ai.law",
"host": "www.ai.law",
"id": 141835
},
"month": 202603,
"week": 1
}
],
"weekHostStatistics": [
{
"month": 202603,
"week": 1,
"adsHostAdvertiserWeeklyList": [
{
"id": 900001,
"adCount": 8,
"advertiserId": 39687,
"hostId": 141835,
"month": 202603,
"week": 1,
"host": {
"domain": "ai.law",
"host": "www.ai.law",
"id": 141835
},
"countries": [
{
"adCount": 8,
"country": "US",
"countryName": "United States"
}
]
}
]
}
]
}
}
}Response Fields
| Field | Description |
|---|---|
data.endpoint | Fixed value: ads-statistics |
data.action | Fixed value: advertiserStatistics |
data.costCredits | Credits consumed by this request |
data.remainingCredits | Remaining credits after deduction |
data.query.action | Normalized action name |
data.query.advertiserId | Plain advertiser ID |
data.query.startDay | Normalized start date |
data.query.endDay | Normalized end date |
data.result.adsAdvertiser | Advertiser profile |
data.result.hostWeekStatistics | Active weekly host breakdown for the advertiser; zero-count host/week rows are omitted |
data.result.hostWeekStatistics[].host | Host profile for that row |
data.result.hostWeekStatistics[].adCount | Ad count for that host/week |
data.result.weekHostStatistics | Week-grouped detailed rows |
data.result.weekHostStatistics[].adsHostAdvertiserWeeklyList | Active detailed weekly records |
data.result.weekHostStatistics[].adsHostAdvertiserWeeklyList[].advertiserId | Plain advertiser ID |
data.result.weekHostStatistics[].adsHostAdvertiserWeeklyList[].hostId | Plain host ID |
data.result.weekHostStatistics[].adsHostAdvertiserWeeklyList[].countries | Country-level ad counts |