{ "openapi": "3.0.1", "info": { "title": "Google Ads Transparency API — Real-time Ad Lookup", "description": "Real-time HTTP API over the Google Ads Transparency Center (ad library). GET /ads with a domain, brand or advertiser ID returns its ads: text (OCR for image-only ads), image, YouTube ID, per-country impressions (EEA/TR), platforms, targeting, topic, Shopping price. Pay per ad.", "version": "0.1", "x-build-id": "IbdenkipJMsrTcASZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/foxlabs~google-ads-transparency-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-foxlabs-google-ads-transparency-api", "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/foxlabs~google-ads-transparency-api/runs": { "post": { "operationId": "runs-sync-foxlabs-google-ads-transparency-api", "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/foxlabs~google-ads-transparency-api/run-sync": { "post": { "operationId": "run-sync-foxlabs-google-ads-transparency-api", "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", "required": [ "queries" ], "properties": { "queries": { "title": "Domains, brands, advertiser IDs or URLs", "type": "array", "description": "One per line. A website domain (nike.com) finds the ads that lead to it, whoever runs them. A brand name (Nike) is matched to the advertiser with that name, or the closest one. An advertiser ID (AR…) or an Ads Transparency Center advertiser/creative URL is used as is.", "items": { "type": "string" } }, "region": { "title": "Region", "enum": [ "anywhere", "AF", "AL", "DZ", "AS", "AD", "AO", "AI", "AQ", "AG", "AR", "AM", "AW", "AU", "AT", "AZ", "BH", "BD", "BB", "BY", "BE", "BZ", "BJ", "BM", "BT", "BO", "BA", "BW", "BV", "BR", "IO", "VG", "BN", "BG", "BF", "BI", "CV", "KH", "CM", "CA", "BQ", "KY", "CF", "TD", "CL", "CN", "CX", "CC", "CO", "KM", "CK", "CR", "CI", "HR", "CW", "CY", "CZ", "CD", "DK", "DJ", "DM", "DO", "EC", "EG", "SV", "GQ", "ER", "EE", "SZ", "ET", "FK", "FO", "FJ", "FI", "FR", "GF", "PF", "TF", "GA", "GE", "DE", "GH", "GI", "GR", "GL", "GD", "GP", "GU", "GT", "GG", "GN", "GW", "GY", "HT", "HM", "HN", "HK", "HU", "IS", "IN", "ID", "IQ", "IE", "IM", "IL", "IT", "JM", "JP", "JE", "JO", "KZ", "KE", "KI", "XK", "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", "MK", "MP", "NO", "OM", "PK", "PW", "PS", "PA", "PG", "PY", "PE", "PH", "PN", "PL", "PT", "PR", "QA", "CG", "RE", "RO", "RW", "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", "TW", "TJ", "TZ", "TH", "BS", "GM", "TL", "TG", "TK", "TO", "TT", "TN", "TR", "TM", "TC", "TV", "VI", "UG", "UA", "AE", "GB", "US", "UM", "UY", "UZ", "VU", "VA", "VE", "VN", "WF", "EH", "YE", "ZM", "ZW" ], "type": "string", "description": "Only ads shown in this country. \"Anywhere\" returns ads from every region. Impression counts are published by Google for the EEA and Turkey only.", "default": "anywhere" }, "adFormat": { "title": "Ad format", "enum": [ "all", "text", "image", "video" ], "type": "string", "description": "Text ads include Shopping product ads. Image ads carry their text inside the picture.", "default": "all" }, "platform": { "title": "Google platform", "enum": [ "all", "search", "youtube", "maps", "play", "shopping" ], "type": "string", "description": "Where the ad was shown.", "default": "all" }, "datePreset": { "title": "Shown during", "enum": [ "any", "last7", "last30", "last90", "last365", "custom" ], "type": "string", "description": "Only ads that were shown at some point in this period (filter applied by Google).", "default": "any" }, "dateFrom": { "title": "From (custom)", "type": "string", "description": "Start date, format YYYY-MM-DD. Used when \"Shown during\" is \"Custom dates below\" or \"Any time\"; a fixed period such as \"Last 30 days\" takes precedence." }, "dateTo": { "title": "To (custom)", "type": "string", "description": "End date, format YYYY-MM-DD. Used when \"Shown during\" is \"Custom dates below\" or \"Any time\"; a fixed period such as \"Last 30 days\" takes precedence." }, "maxAdsPerQuery": { "title": "Max ads per query", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many ads for each query. Large advertisers have tens of thousands. The form starts at 10 for a quick first run; an API call without this field gets 100.", "default": 100 }, "maxAdvertisersPerQuery": { "title": "Advertisers per brand name", "minimum": 1, "maximum": 20, "type": "integer", "description": "For brand-name queries only: how many matching advertiser accounts to include (best match first). A brand often runs ads from several legal entities.", "default": 1 }, "includeDetails": { "title": "Regions, impressions, surfaces, targeting and topic", "type": "boolean", "description": "One extra request per ad. Adds first/last shown per country, impression ranges and platform breakdown (EEA and Turkey), audience-targeting approach, topic and variation count.", "default": true }, "includeAdCopy": { "title": "Ad copy, landing page and YouTube video", "type": "boolean", "description": "Reads the ad preview: text lines, call to action, display URL, YouTube video ID, Shopping product title, price and merchant, and the landing URL when the preview has one. Ads that Google keeps only as a picture (most image ads and many search ads) are read by the option below.", "default": true }, "ocrImageAds": { "title": "Read the text of image-only ads (OCR)", "type": "boolean", "description": "Google keeps many ads only as a picture. With this on, the text in the picture is read (OCR) into the text fields, with adCopyStatus \"ocr\" and an ocrConfidence score. Latin-script languages: English, German, French, Spanish, Portuguese, Italian, Dutch, Polish, Turkish. Needs \"Ad copy\" on; counted as ad copy.", "default": true }, "includeAdvertiserDetails": { "title": "Advertiser legal name and country", "type": "boolean", "description": "Adds the advertiser's legal name, billing country and, where Google publishes it, the D-U-N-S number.", "default": true }, "onlyNewAds": { "title": "Only ads not seen in earlier runs", "type": "boolean", "description": "Monitoring mode for scheduled runs: returns only ads this monitor has not returned before. A run sees at most \"Max ads per query\" ads, so combine it with a \"Shown during\" period (e.g. last 7 days) that the first run can fully cover.", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Keeps separate memories for separate monitors (for example one per client). Stored in your own key-value store." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Not needed for most runs. Leave off and the Actor switches to Apify residential proxy by itself if Google rate-limits it.", "default": { "useApifyProxy": false } }, "autoProxyFallback": { "title": "Switch to residential proxy when rate-limited", "type": "boolean", "description": "When Google answers \"too many requests\", continue through Apify residential proxy instead of failing.", "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 } } } } } } } } } }