{
"openapi": "3.0.1",
"info": {
"title": "Google Ads Monitor: Competitor Search Ads & Ad Copy Changes",
"description": "See which competitors run Google search ads on your keywords, in any country or city. Get headlines, descriptions, positions and sitelinks, and a monitor mode that reports new advertisers, new ad copy and advertisers that stopped.",
"version": "0.1",
"x-build-id": "PVrEiQyJ1N2sKSIlW"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/southern-data~google-search-ads-monitor/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-southern-data-google-search-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/southern-data~google-search-ads-monitor/runs": {
"post": {
"operationId": "runs-sync-southern-data-google-search-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/southern-data~google-search-ads-monitor/run-sync": {
"post": {
"operationId": "run-sync-southern-data-google-search-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": {
"keywords": {
"title": "Keywords",
"type": "array",
"description": "Search terms to check for ads, one per line — the words your customers type, e.g. \"emergency plumber sydney\". Each keyword is loaded on Google checks per keyword times; every page load is one paid check.",
"items": {
"type": "string"
}
},
"country": {
"title": "Country",
"enum": [
"us",
"au",
"gb",
"ca",
"nz",
"ie",
"in",
"sg",
"za",
"ph",
"my",
"hk",
"ae",
"ng",
"ke",
"pk",
"de",
"at",
"ch",
"fr",
"be",
"nl",
"es",
"it",
"pt",
"br",
"mx",
"ar",
"co",
"cl",
"pe",
"se",
"no",
"dk",
"fi",
"pl",
"cz",
"ro",
"hu",
"gr",
"tr",
"il",
"sa",
"eg",
"jp",
"kr",
"tw",
"id",
"th",
"vn"
],
"type": "string",
"description": "Google site and searcher location. Ads are fetched through Apify's Google proxy in this country, so you see the ads people there see.",
"default": "us"
},
"location": {
"title": "City / region (optional)",
"type": "string",
"description": "Localise to a city, region or postcode. Type it like \"Sydney, NSW\", \"Austin, TX\", \"London, England\" or Google's full name \"Sydney,New South Wales,Australia\". It is checked against Google's own list of places before any search (free): typos get suggestions, and a place in another country is refused. Leave empty for the whole country. Local ads (plumbers, dentists, lawyers) show far more often with a city set."
},
"language": {
"title": "Language (optional)",
"type": "string",
"description": "Google interface language code, e.g. en, de, pt-BR. Empty = the country's main language."
},
"device": {
"title": "Device",
"enum": [
"desktop",
"mobile"
],
"type": "string",
"description": "Desktop and mobile can show different ads.",
"default": "desktop"
},
"checksPerKeyword": {
"title": "Checks per keyword",
"minimum": 1,
"maximum": 10,
"type": "integer",
"description": "How many times each keyword is loaded on Google in this run. Google does NOT show ads on every page load (in our tests: 33–58% of loads country-wide, 50–94% with a city set), and rotates advertisers, so 2–3 checks find many more ads than 1. Each check is one paid event; results merge into one row per ad with \"seen in X of Y checks\".",
"default": 2
},
"stopWhenAdsFound": {
"title": "Stop after the first check that shows ads",
"type": "boolean",
"description": "Cheaper: once a check of a keyword shows ads, skip its remaining checks. You may miss advertisers that rotate in on other loads.",
"default": false
},
"competitorDomains": {
"title": "Competitor domains (optional)",
"type": "array",
"description": "Websites to flag, e.g. \"competitor.com\" (subdomains count). Their ads get isCompetitor = true.",
"items": {
"type": "string"
}
},
"myDomain": {
"title": "Your domain (optional)",
"type": "string",
"description": "Your own site, e.g. \"mybusiness.com.au\". Your ads get isYou = true, so you can see where you show and where you don't."
},
"onlyCompetitors": {
"title": "Only return competitor (and your) ads",
"type": "boolean",
"description": "Hide ads from other advertisers. The ADVERTISERS record still lists everyone.",
"default": false
},
"mode": {
"title": "Mode",
"enum": [
"all_ads",
"changes"
],
"type": "string",
"description": "changes: remembers each keyword's advertisers and ad texts between runs and returns only what is new: new advertisers, new ad copy, advertisers that came back or stopped showing. The first run returns everything as \"baseline\". Schedule it daily or weekly. Google rotates each advertiser's ad texts, so new ad copy is only reported after an advertiser has been seen on about 6 page loads (texts seen before that are learned silently).",
"default": "all_ads"
},
"monitorName": {
"title": "Monitor name (changes mode)",
"type": "string",
"description": "Memory name, e.g. \"plumbing-competitors\". Keep it the same between runs; changing it starts a fresh baseline. Empty = a name made from the keywords and settings (or the saved task)."
},
"includeUnchanged": {
"title": "Also return unchanged ads (changes mode)",
"type": "boolean",
"description": "Return every ad with change = unchanged as well, for a full picture each run.",
"default": false
},
"goneAfterRuns": {
"title": "Report an advertiser as gone after N runs (changes mode)",
"minimum": 1,
"maximum": 20,
"type": "integer",
"description": "An advertiser is reported advertiser_gone after this many runs in a row where the keyword showed ads but none of theirs. Runs where Google showed no ads at all don't count. Higher = fewer false alarms.",
"default": 3
},
"selfTest": {
"title": "Self-test",
"type": "boolean",
"description": "Maintenance: check the parser on saved pages plus one live Google check. Ignores the other fields.",
"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
}
}
}
}
}
}
}
}
}
}