{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Report: Competitor Ads", "description": "Google Ads Transparency Center scraper for competitor monitoring: every ad by domain, advertiser or brand, with run dates, countries, formats and ad copy read from the ad or its image (OCR). Get a weekly report of new, stopped and long-running ads. Never reports zero ads when Google refused.", "version": "0.1", "x-build-id": "CRBl26CbqjdSRsrtT" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/firsthand~google-ads-transparency-report/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-firsthand-google-ads-transparency-report", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/firsthand~google-ads-transparency-report/runs": { "post": { "operationId": "runs-sync-firsthand-google-ads-transparency-report", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/firsthand~google-ads-transparency-report/run-sync": { "post": { "operationId": "run-sync-firsthand-google-ads-transparency-report", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "domains": { "title": "Competitor domains", "type": "array", "description": "Domains to look up in the Google Ads Transparency Center (hubspot.com). Links with https://, www. and a path are fine. A domain returns ads from every account advertising it, agencies and job boards included, so each row carries both the domain and the advertiser.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser ids", "type": "array", "description": "Advertiser ids from the Transparency Center, the AR... part of a link like adstransparency.google.com/advertiser/AR04545223091738902529. Rows found this way have no domain: the source does not return one for advertiser lookups.", "items": { "type": "string" } }, "startUrls": { "title": "Transparency Center links", "type": "array", "description": "Links copied from adstransparency.google.com: an advertiser page (/advertiser/AR...) or a domain search (?domain=...). A link to a single ad returns its advertiser. The region in a link is used when the Country field below is empty.", "items": { "type": "string" } }, "searchQueries": { "title": "Brand names", "type": "array", "description": "Company or brand names (Zalando, Domino's). The Transparency Center's own name search finds advertisers whose name matches, and the actor returns their ads. It matches advertiser names, not the text of ads. Each ad found by a name says which name found it, unless another input of the same run returned that ad first.", "items": { "type": "string" } }, "maxAdvertisersPerQuery": { "title": "Advertisers per brand name", "minimum": 1, "maximum": 50, "type": "integer", "description": "How many of the matching advertisers to take for each brand name, in the order the Transparency Center lists them. Big brands have several accounts per country.", "default": 3 }, "country": { "title": "Country", "pattern": "^([A-Za-z]{2})?$", "type": "string", "description": "Two-letter country code (US, DE, JP). Only ads shown in this country. Leave empty for all countries. One country per run: given several, the source uses only the first." }, "adFormat": { "title": "Ad format", "enum": [ "all", "text", "image", "video" ], "type": "string", "description": "Only text, image or video ads.", "default": "all" }, "platform": { "title": "Platform", "enum": [ "all", "search", "youtube", "shopping", "maps", "play" ], "type": "string", "description": "Only ads shown on one Google platform. The Transparency Center's platform filter only covers ads shown on or after 4 September 2023; older ads never appear when a platform is chosen.", "default": "all" }, "shownAfter": { "title": "Shown on or after", "type": "string", "description": "Only ads shown on or after this day (YYYY-MM-DD). Every ad is checked against its own first and last shown dates. The Transparency Center lists ads from the most recently shown, so reading stops at the first ad last shown before this day; if the run sees that order broken, it reads the whole list instead. The targets report says how many ads were left out." }, "shownBefore": { "title": "Shown on or before", "type": "string", "description": "Only ads first shown on or before this day (YYYY-MM-DD)." }, "fastPeriodFilter": { "title": "Fast period filter (misses some ads)", "type": "boolean", "description": "Pass the period to the Transparency Center's own date filter: about half the requests and time on large advertisers, but that filter misses some ads, mostly long-running ones: 0.7% for the last 30 days and up to 5% for older months (measured 11.09.2026). It only reaches about 11 months back; older periods are filtered the complete way anyway.", "default": false }, "maxAdsPerTarget": { "title": "Max ads per domain or advertiser", "minimum": 1, "type": "integer", "description": "Safety cap, counted after filters. Large brands run thousands of ads. A target cut by this cap is reported with status partial in the targets report, never as complete.", "default": 200 }, "adDetails": { "title": "Fetch ad text, countries and impressions", "type": "boolean", "description": "Adds the countries where each ad was shown, impression ranges where the Transparency Center publishes them (mostly for ads shown in the EU) and, where it keeps the ad as HTML, its text: headline, description, display and landing URL (with the campaign's UTM tags when the ad has them) and the YouTube video id for video ads. Many text ads are archived only as a picture of the ad: then image_url holds that picture, text_available is false and the text fields stay empty. How much of the link you get depends on the format, measured 22.09.2026 on 250 ads across 50 domains: the landing URL and its UTM tags come with 94% of video ads (UTM tags in 36% of them, the advertiser's own choice), about 14% of image ads and 0% of text ads, because Google publishes no link for a text ad at all; for those the display URL is read off the picture instead, in 93% of cases, when 'Read text from ad pictures (OCR)' is on. The countries and impressions card is one small request per ad and is charged as the ad details event. Ad text read from the source is charged as a separate, pricier ad text event, because the ad preview file it comes from is about 300 KB.", "default": false }, "ocrTextAds": { "title": "Read text from ad pictures (OCR)", "type": "boolean", "description": "Most text ads (94% of 6,095 on 194 company domains, measured 11.09.2026) are archived by the Transparency Center only as a picture of the ad, with no text. This reads the headline, description, display URL and sitelinks from that picture with Tesseract OCR. It runs on text ads only, because those are the ones the source archives as a picture; image and video ads say so in their OCR column. Recognised text can contain OCR errors, so such rows have text_source \"ocr\" and an ocr_confidence score; text taken from the source itself has text_source \"source\". Some Maps ads are archived as an empty layout with no text at all; they are marked in ocr_status. Charged as a separate event, only for ads whose text was read.", "default": false }, "maxDetailsPerTarget": { "title": "Max ads with details per target", "minimum": 1, "type": "integer", "description": "Fetch text, countries and impressions (and OCR text) only for the first N ads of each target, in the order the Transparency Center lists them. The other ads still come back with their format, dates and preview, but their text fields stay empty and their Details and OCR columns say they were past this limit. Use it to cap the cost of text; leave it empty to get text for every ad." }, "enrichWorkers": { "title": "Ads fetched at the same time", "minimum": 1, "maximum": 16, "type": "integer", "description": "How many ads have their details and OCR read in parallel. Measured 22 September 2026: about 10 seconds per enriched ad one at a time and 2 to 3.5 seconds six at a time, and the run waits on the network for almost all of it, so raising this is what makes a large run fit into the run timeout. Lower it to 1 if the Transparency Center starts refusing your requests: the run gets slower but finishes.", "default": 6 }, "reportDays": { "title": "Competitor report period", "minimum": 1, "maximum": 365, "type": "integer", "description": "Adds a competitor report for the last N days: one row per domain and advertiser with ads running now, new ads, stopped ads and long-running ads, by format and by country, plus the unique ad messages (headline and description) with how many creatives use each. An ad counts as running now when it was last shown within 48 hours: the Transparency Center updates this date with a delay of up to a day and a half (measured on 10,888 ads). An ad counts as stopped when it passed that 48-hour mark during the period, so daily reports on a schedule never miss a stop. When Shown on or after is empty, reading starts two days before the period (to see those stops) and stops at the first older ad, so scheduled runs stay cheap. Messages need ad text: turn on details or OCR." }, "longRunnerDays": { "title": "Long-running ad after", "minimum": 1, "type": "integer", "description": "An ad running now that has been shown for at least this many days counts as long-running. This is a convention, not something the source tells: long-running ads are usually the ones that work.", "default": 30 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Required. Google blocks a single IP after a few dozen requests, so every request goes through a rotating proxy. Only Apify's Residential group gets through: datacenter IPs are refused by the Transparency Center, and the Google SERP and Unblocker groups cannot reach it at all, so any other Apify proxy group is switched to Residential for the run, with a note in the log. Your own proxy URLs are used as given.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }