{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency Scraper: Competitor Ad Library", "description": "See every competitor ad in the Google Ads Transparency Center. Search by brand, website or advertiser ID and get ad text, images, YouTube videos, format, first and last shown dates, regions and EU reach. No login, no proxy fees.", "version": "1.0", "x-build-id": "ml22BMCxvGNhwJRNU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/mosaicked_sponge~google-ads-transparency-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-mosaicked_sponge-google-ads-transparency-scraper", "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/mosaicked_sponge~google-ads-transparency-scraper/runs": { "post": { "operationId": "runs-sync-mosaicked_sponge-google-ads-transparency-scraper", "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/mosaicked_sponge~google-ads-transparency-scraper/run-sync": { "post": { "operationId": "run-sync-mosaicked_sponge-google-ads-transparency-scraper", "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": "Websites (domains)", "type": "array", "description": "Every ad that sends people to these websites, from any advertiser account. Example: nike.com, hellofresh.com.", "items": { "type": "string" } }, "queries": { "title": "Brand names or keywords", "type": "array", "description": "Free text such as \"Nike\" or \"Grammarly\". It is matched to advertiser accounts with Google's own Transparency Center search (the biggest matching account first). Domains and AR... IDs typed here work too.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "IDs that start with AR, from the advertiser's page URL, e.g. AR16735076323512287233.", "items": { "type": "string" } }, "startUrls": { "title": "Transparency Center links", "type": "array", "description": "Paste advertiser, single-ad (creative) or domain-search links copied from adstransparency.google.com.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxAdsPerTarget": { "title": "Max ads per advertiser / website", "minimum": 1, "maximum": 20000, "type": "integer", "description": "Stop after this many ads for each target. You pay only for ads saved.", "default": 20 }, "maxTotalAds": { "title": "Max ads in the whole run (0 = no limit)", "minimum": 0, "type": "integer", "description": "A hard cap across all targets. You can also set a maximum cost per run in the run options.", "default": 0 }, "region": { "title": "Region", "enum": [ "anywhere", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BS", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BQ", "BA", "BW", "BV", "BR", "IO", "BN", "BG", "BF", "BI", "CV", "KH", "CM", "CA", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CG", "CD", "CK", "CR", "HR", "CU", "CW", "CY", "CZ", "CI", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GM", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "VA", "HN", "HK", "HU", "IS", "IN", "ID", "IR", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "KW", "KG", "LA", "LV", "LB", "LS", "LR", "LY", "LI", "LT", "LU", "MO", "MG", "MW", "MY", "MV", "ML", "MT", "MH", "MQ", "MR", "MU", "YT", "MX", "FM", "MD", "MC", "MN", "ME", "MS", "MA", "MZ", "MM", "NA", "NR", "NP", "NL", "NC", "NZ", "NI", "NE", "NG", "NU", "NF", "KP", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "RO", "RU", "RW", "RE", "BL", "SH", "KN", "LC", "MF", "PM", "VC", "WS", "SM", "ST", "SA", "SN", "RS", "SC", "SL", "SG", "SX", "SK", "SI", "SB", "SO", "ZA", "GS", "KR", "SS", "ES", "LK", "SD", "SR", "SJ", "SE", "CH", "SY", "TW", "TJ", "TZ", "TH", "TL", "TG", "TK", "TO", "TT", "TN", "TM", "TC", "TV", "TR", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VE", "VN", "VG", "VI", "WF", "EH", "YE", "ZM", "ZW", "AX" ], "type": "string", "description": "Only ads shown in this country. \"Anywhere\" returns ads from every country.", "default": "anywhere" }, "adFormat": { "title": "Ad format", "enum": [ "ALL", "TEXT", "IMAGE", "VIDEO" ], "type": "string", "description": "Google's own format filter.", "default": "ALL" }, "platforms": { "title": "Platforms", "type": "array", "description": "Leave empty for all. Google applies platform filters only to ads shown since 4 Sep 2023.", "items": { "type": "string", "enum": [ "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "enumTitles": [ "Google Search", "YouTube", "Google Shopping", "Google Maps", "Google Play" ] } }, "startDate": { "title": "Shown from", "type": "string", "description": "Only ads shown on or after this date (YYYY-MM-DD). Google answers date filters for roughly the last 12 months." }, "endDate": { "title": "Shown until", "type": "string", "description": "Only ads shown on or before this date (YYYY-MM-DD). Empty = today." }, "maxAdvertisersPerQuery": { "title": "Advertiser accounts per brand name", "minimum": 1, "maximum": 10, "type": "integer", "description": "How many matching advertiser accounts to take for each brand name / keyword (biggest first).", "default": 1 }, "includeDetails": { "title": "Include full ad details (free)", "type": "boolean", "description": "Every country the ad ran in with dates, EU impressions ranges per country and platform, audience targeting, all variations, and the ad's headline, description, landing page and YouTube video. No extra charge; turn off only for the fastest possible runs.", "default": true }, "readTextFromSnapshots": { "title": "Read text ads that Google only kept as a picture", "type": "boolean", "description": "Many search text ads are archived by Google only as a rendered picture (the Transparency Center page shows that picture). We read the headline, description and display URL from it with OCR (textSource = ocr_snapshot, with ocrConfidence). No extra cost.", "default": true }, "chargeTextAdsWithoutText": { "title": "Charge for text ads without readable text", "type": "boolean", "description": "Off (default): a text ad whose text Google did not keep in any readable form is still saved with its dates, regions and links, but with status text_unavailable and NOT charged. Turn on to treat these like normal ads.", "default": false }, "includeAdvertiserInfo": { "title": "Include advertiser legal name, country and verified badge", "type": "boolean", "description": "One small lookup per advertiser, cached for the run.", "default": true }, "onlyNewAds": { "title": "Monitor mode: only ads not seen in earlier runs", "type": "boolean", "description": "Remembers every ad ID it has saved in a named key-value store, so scheduled runs return (and charge) only new ads.", "default": false }, "monitorStoreName": { "title": "Monitor memory name", "type": "string", "description": "Use a different name per competitor or schedule so their histories don't mix. Letters, digits and dashes.", "default": "ads-transparency-monitor" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Leave off for most runs: the scraper connects directly and switches to Apify datacenter proxy automatically if Google slows it down. If you turn Apify Proxy on here, it is used from the start.", "default": { "useApifyProxy": false } }, "residentialFallback": { "title": "Allow residential proxy as a last resort (no extra cost to you)", "type": "boolean", "description": "Used only if both the direct connection and Apify datacenter proxy are rate-limited by Google, and only for the small data requests (ad images and previews never go through it). The proxy cost is covered by the Actor's price. Turn off to never use residential IPs.", "default": true } } }, "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 } } } } } } } } } }