{ "openapi": "3.0.1", "info": { "title": "Google Ads Monitor — Competitor Ads Tracker", "description": "Google Ads Transparency scraper and competitor ad monitor. Get ad text, images, videos, impressions by country and platform, targeting and dates. Monitoring mode returns only new, stopped and resumed ads and new countries. Pay only per result.", "version": "0.3", "x-build-id": "EDQYcr6pdVFDYtkme" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/violet_lab~google-ads-monitor/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-violet_lab-google-ads-monitor", "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/violet_lab~google-ads-monitor/runs": { "post": { "operationId": "runs-sync-violet_lab-google-ads-monitor", "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/violet_lab~google-ads-monitor/run-sync": { "post": { "operationId": "run-sync-violet_lab-google-ads-monitor", "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": "Advertised domains", "type": "array", "description": "Domains the ads point to, e.g. nike.com. Finds ads from every advertiser account that promotes the domain.", "items": { "type": "string" } }, "brandNames": { "title": "Brand / advertiser names", "type": "array", "description": "Advertiser name as shown in Google Ads Transparency Center. Resolved to the best-matching verified advertiser.", "items": { "type": "string" } }, "advertiserIds": { "title": "Advertiser IDs", "type": "array", "description": "IDs like AR16735076323512287233 (from the advertiser URL in Ads Transparency Center).", "items": { "type": "string" } }, "region": { "title": "Region (country code)", "type": "string", "description": "ISO country code where ads were shown, e.g. US, DE, GB. Empty = all regions." }, "platform": { "title": "Platform", "enum": [ "SEARCH", "YOUTUBE", "SHOPPING", "MAPS", "PLAY" ], "type": "string", "description": "Optional: only ads shown on this Google platform." }, "dateFrom": { "title": "Shown from (YYYY-MM-DD)", "type": "string", "description": "Optional start date." }, "dateTo": { "title": "Shown until (YYYY-MM-DD)", "type": "string", "description": "Optional end date." }, "onlyNewAds": { "title": "Monitoring mode: only changes since last run", "type": "boolean", "description": "Remember ads between runs and output only changes: NEW ads, STOPPED ads (not shown for more than 'active within days'), RESUMED ads and — with ad details on — NEW_REGION (ad started showing in a new country). Combine with an Apify Schedule (e.g. daily).", "default": false }, "activeWithinDays": { "title": "Monitoring: ad is active if shown within (days)", "minimum": 1, "type": "integer", "description": "An ad not shown for longer than this is reported as STOPPED.", "default": 2 }, "skipExistingOnFirstRun": { "title": "Monitoring: first run only records a baseline", "type": "boolean", "description": "In monitoring mode, the first run stores currently live ads without outputting (or charging for) them.", "default": true }, "includeAdvertiserDetails": { "title": "Include advertiser details", "type": "boolean", "description": "Adds the advertiser's verified legal name and country.", "default": false }, "includeAdDetails": { "title": "Include ad details (impressions, targeting, text)", "type": "boolean", "description": "For each ad: impressions by country and platform (ranges published by Google), targeting categories, days served, all variations, ad text when available, video link. One extra request per ad; charged as 'Ad details'.", "default": false }, "includePreviewText": { "title": "Ad details: read text from ad preview", "type": "boolean", "description": "When Google does not expose the ad copy directly, read visible texts from the rendered preview (adTexts). Slower.", "default": true }, "ocrTextAds": { "title": "Ad details: OCR text ads (headline, description)", "type": "boolean", "description": "For text ads Google often publishes only a screenshot. Read the headline, display URL and description from it (textSource = 'ocr'). Included in the 'Ad details' price.", "default": true }, "includeSummary": { "title": "Add summary per competitor", "type": "boolean", "description": "Adds one free 'summary' record per domain/advertiser: active ads, launched in last 7 days, formats, top advertisers, top countries and (in monitoring) counts of changes.", "default": false }, "maxAdsPerTarget": { "title": "Max ads per domain/advertiser", "minimum": 1, "type": "integer", "description": "Stop after this many ads for each domain / advertiser.", "default": 200 }, "maxAdsTotal": { "title": "Max ads in total", "minimum": 1, "type": "integer", "description": "Stop after this many ads in total across all targets (cost cap).", "default": 1000 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Google rate-limits single IPs after a few dozen requests. Apify Proxy rotates sessions automatically when blocked.", "default": { "useApifyProxy": true } }, "requestIntervalSecs": { "title": "Delay between requests (s)", "minimum": 0, "type": "number", "description": "Pause between requests to Google. Higher = slower but less likely to be rate-limited.", "default": 1 }, "diagnostic": { "title": "Diagnostic mode (developer only)", "type": "boolean", "description": "Internal: probe proxies and store raw Google responses. Not for normal use.", "default": false }, "residentialFallback": { "title": "Auto-switch to residential proxy when blocked", "type": "boolean", "description": "Starts on cheap datacenter proxy; if Google blocks it, switches to Apify RESIDENTIAL proxy automatically (no extra charge to you).", "default": true }, "detailConcurrency": { "title": "Parallel ad-detail requests", "minimum": 1, "maximum": 20, "type": "integer", "description": "How many ads are enriched with details at the same time.", "default": 5 }, "downloadImages": { "title": "Save ad images", "type": "boolean", "description": "Copy ad images (up to 5 per ad) to this run's key-value store and return permanent links in storedImageUrls. Google preview links can expire.", "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 } } } } } } } } } }