{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper - Ad Text & Copy", "description": "Google Ads scraper for the Ads Transparency Center with ad text included at no extra charge: headlines, descriptions, display URLs & YouTube titles. Track competitor ads by domain or advertiser, OCR for screenshot ads, only-new-ads mode.", "version": "0.2", "x-build-id": "IoGHFKPs6xL4EePCI" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ferncrawl~google-ads-transparency-ad-text/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ferncrawl-google-ads-transparency-ad-text", "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/ferncrawl~google-ads-transparency-ad-text/runs": { "post": { "operationId": "runs-sync-ferncrawl-google-ads-transparency-ad-text", "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/ferncrawl~google-ads-transparency-ad-text/run-sync": { "post": { "operationId": "run-sync-ferncrawl-google-ads-transparency-ad-text", "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": "Advertiser domains", "type": "array", "description": "Websites whose ads you want, e.g. nike.com. Matches every advertiser account that advertises this domain.", "items": { "type": "string" } }, "advertiserNames": { "title": "Advertiser names", "type": "array", "description": "Legal / verified advertiser names, e.g. 'Nike, Inc.'. Resolved through the Transparency Center search box (Latin-script names work best).", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs (AR…)", "type": "array", "description": "Exact advertiser IDs from an adstransparency.google.com/advertiser/AR… URL. Most precise option.", "items": { "type": "string" } }, "nameMatch": { "title": "Name matching", "enum": [ "best", "all" ], "type": "string", "description": "For advertiser names: take the single best match, or all advertisers Google suggests.", "default": "best" }, "regions": { "title": "Regions", "type": "array", "description": "ISO country codes (US, TW, GB, JP…) or 'anywhere'. Several regions are scraped in one run and merged per ad.", "default": [ "anywhere" ], "items": { "type": "string" } }, "formats": { "title": "Ad formats", "type": "array", "description": "Leave empty for all formats.", "items": { "type": "string", "enum": [ "TEXT", "IMAGE", "VIDEO" ], "enumTitles": [ "Text", "Image", "Video" ] } }, "dateFrom": { "title": "Shown from (YYYY-MM-DD)", "type": "string", "description": "Only ads shown on/after this date." }, "dateTo": { "title": "Shown until (YYYY-MM-DD)", "type": "string", "description": "Only ads shown on/before this date." }, "lastNDays": { "title": "…or last N days", "minimum": 1, "maximum": 3650, "type": "integer", "description": "Overrides the dates above." }, "maxAdsPerAdvertiser": { "title": "Max ads per advertiser/domain", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many ads per advertiser/domain (across all regions and formats). Higher = more cost.", "default": 100 }, "extractAdText": { "title": "Extract ad text from previews", "type": "boolean", "description": "Decode each ad's rendered preview to get headline, description and display URL. Included in the per-ad price.", "default": true }, "ocr": { "title": "OCR (read text from ad images)", "enum": [ "auto", "off", "all" ], "type": "string", "description": "Auto (default): OCR runs only on text-format ads that Google stores as a screenshot, so their headline/description/display URL would otherwise be empty (common for US search ads). Image and video ads are not OCR'd. Off: no OCR at all (fastest). All: OCR every image ad including banners — slow, and banners often contain little readable copy. Text from live previews and YouTube video titles is extracted in every mode. OCR takes ~9 s per image at 1024 MB and is charged per image actually OCR'd. Use at least 1024 MB memory when OCR can run.", "default": "auto" }, "fetchDetails": { "title": "Fetch per-ad details (all regions, variations)", "type": "boolean", "description": "One extra request per ad: every country the ad ran in, last date per country, number of variations. Charged per ad.", "default": false }, "monitorMode": { "title": "Monitoring mode (new / removed ads)", "type": "boolean", "description": "Compares with the previous run of the same query and labels each ad new/existing; ads that disappeared are output as 'removed'. Schedule the actor daily for competitor alerts.", "default": false }, "onlyNewAds": { "title": "Only new ads (skip ads already returned)", "type": "boolean", "description": "Remembers the ads this query already returned (per domain/advertiser + regions + formats, in a key-value store in your own Apify account) and outputs only ads you have not received before. Skipped ads are not charged. The first run returns ads normally and builds the memory. Ideal with a daily schedule.", "default": false }, "sinceDate": { "title": "Only ads first shown on/after (YYYY-MM-DD)", "type": "string", "description": "Optional. Keeps only ads whose first-shown date is on or after this date (newly launched ads). Older ads are skipped and not charged. Works with or without 'Only new ads'." }, "minRequestIntervalSecs": { "title": "Min seconds between requests", "minimum": 0.5, "type": "number", "description": "Politeness delay. Lower = faster but Google may show its anti-bot page.", "default": 3 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Required in practice: Google blocks cloud data-center IPs without a proxy. Apify Proxy (datacenter) is on by default; sessions rotate automatically if Google rate-limits.", "default": { "useApifyProxy": true } }, "proxyAssets": { "title": "Send image/preview downloads through the proxy too", "type": "boolean", "description": "Off (recommended): only the Transparency Center search queries use the proxy. Preview scripts and ad images come from other Google hosts that don't rate-limit, so this keeps proxy traffic ~50x smaller.", "default": false } } }, "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 } } } } } } } } } }