{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Center Scraper – Competitor Ads",
    "description": "Export a competitor's Google ads from the Ads Transparency Center by brand, website domain or advertiser ID: ad text, format, first/last shown, countries, YouTube links, EU reach. 'Only new ads' mode for scheduled alerts in n8n or Make. Pay per ad. Not affiliated with Google.",
    "version": "0.2",
    "x-build-id": "AORvbfuKVircyeTgk"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/cleandata-labs~google-ads-transparency-explorer/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-cleandata-labs-google-ads-transparency-explorer",
        "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/cleandata-labs~google-ads-transparency-explorer/runs": {
      "post": {
        "operationId": "runs-sync-cleandata-labs-google-ads-transparency-explorer",
        "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/cleandata-labs~google-ads-transparency-explorer/run-sync": {
      "post": {
        "operationId": "run-sync-cleandata-labs-google-ads-transparency-explorer",
        "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": {
          "queries": {
            "title": "Brand names or websites",
            "type": "array",
            "description": "Brand names or websites to look up, e.g. [\"Nike\"] or [\"hellofresh.com\"]. Names are matched to advertiser accounts that have ads in your regions (see maxAdvertisersPerQuery); if no account matches, the brand's own website is used. You can also paste an advertiser ID (AR...) or an adstransparency.google.com link here. No default: an API call with only domains or advertiserIds scrapes only those.",
            "items": {
              "type": "string"
            }
          },
          "domains": {
            "title": "Domains",
            "type": "array",
            "description": "Exact websites, e.g. [\"nike.com\", \"emag.ro\"]. Returns every ad that points to the domain, from any advertiser account. The most precise way to see a competitor's ads. In \"advertisers\" mode: which accounts advertise this website (a quick Google Ads check for a list of companies).",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Advertiser IDs that start with AR, e.g. [\"AR16735076323512287233\"], taken from an advertiser page URL on adstransparency.google.com.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Ads Transparency Center URLs",
            "type": "array",
            "description": "Optional advertiser, creative or domain-search links copied from adstransparency.google.com, e.g. [{\"url\": \"https://adstransparency.google.com/advertiser/AR16735076323512287233?region=US\"}]. Filters in the URL (region, format, platform, dates) are applied.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "resultType": {
            "title": "Result type",
            "enum": [
              "ads",
              "advertisers"
            ],
            "type": "string",
            "description": "\"ads\" (default) = one row per ad creative. \"advertisers\" = one row per advertiser account with approximate ad count, country, legal name and verification status. Use \"advertisers\" to check who advertises for a brand or website.",
            "default": "ads"
          },
          "regions": {
            "title": "Regions (countries)",
            "type": "array",
            "description": "Country codes where the ads were shown, e.g. [\"US\"] or [\"DE\",\"FR\"] (ads shown in ANY of them). Leave empty / [] = anywhere (default). English names like \"Germany\" also work. Reach and audience data exist only for EU countries.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Optional Google surfaces: any of \"SEARCH\", \"YOUTUBE\", \"SHOPPING\", \"MAPS\", \"PLAY\". [] = all. Google applies this filter only to ads shown since September 2023.",
            "items": {
              "type": "string",
              "enum": [
                "SEARCH",
                "YOUTUBE",
                "SHOPPING",
                "MAPS",
                "PLAY"
              ]
            }
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "ALL",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Creative format: \"ALL\" (default), \"TEXT\", \"IMAGE\" or \"VIDEO\".",
            "default": "ALL"
          },
          "startDate": {
            "title": "Shown on or after",
            "type": "string",
            "description": "Optional. Only ads shown on or after this date, format YYYY-MM-DD, e.g. \"2026-06-01\". Google applies date filters only to about the last 12 months."
          },
          "endDate": {
            "title": "Shown on or before",
            "type": "string",
            "description": "Optional. Only ads shown on or before this date, format YYYY-MM-DD."
          },
          "maxAdsPerTarget": {
            "title": "Max ads per target",
            "minimum": 0,
            "type": "integer",
            "description": "Max ads per domain / advertiser, 0 = no limit. Default 100 (form prefill 10 for a cheap first run). Each ad is one paid result, so AI agents should use 10-20 for a quick look. A brand-name query can expand to several advertisers. With onlyNew on, this caps the NEW ads per run.",
            "default": 100
          },
          "maxAdvertisersPerQuery": {
            "title": "Max advertisers per brand-name query",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many matching advertiser accounts to use per brand-name query, 1-20. Default 3. Exact name matches first, then by ad count. Use 1 for the main brand only.",
            "default": 3
          },
          "includeDetails": {
            "title": "Add full ad details (EU reach, audience, all countries, variations, topic)",
            "type": "boolean",
            "description": "true = one extra request per ad to add all A/B variations, every country with dates, Google's 'times shown' ranges (EU ads), audience selection and topic. Paid add-on per ad and slower (about 1 s per ad). Default false.",
            "default": false
          },
          "includeAdText": {
            "title": "Add ad text, YouTube video ID and product data",
            "type": "boolean",
            "description": "true = read Google's ad preview to add the visible ad text (headline, description, product title, display URL) and the YouTube video ID of video ads. Paid add-on, charged only when text or a video ID was found. Default false.",
            "default": false
          },
          "includeAdvertiserInfo": {
            "title": "Add advertiser identity (free)",
            "type": "boolean",
            "description": "true (default, free) = add advertiser country, legal name, verification status and EU-only flag to each row.",
            "default": true
          },
          "onlyNew": {
            "title": "Only new ads since the last run",
            "type": "boolean",
            "description": "true = remember every ad (or advertiser) returned for this query and, on later runs, return only ones not returned before. Already-seen ads are skipped for free; if nothing is new the dataset is empty and the run costs only the start fee. Memory is kept per query + filters in your named key-value store \"google-ads-transparency-state\" (or under stateKey). The first run returns everything up to maxAdsPerTarget. Default false.",
            "default": false
          },
          "stateKey": {
            "title": "Memory key (optional)",
            "type": "string",
            "description": "Optional name for the onlyNew memory, e.g. \"competitors-ro-daily\". Runs with the same stateKey share one memory, so you can change filters or targets without resetting it. Leave empty to get one memory per query + filters automatically. Use a new key to start fresh."
          },
          "maxAdsToCheck": {
            "title": "onlyNew: max ads to check per target",
            "minimum": 0,
            "type": "integer",
            "description": "Only used with onlyNew, from the second run on. A big advertiser can have tens of thousands of live ads and Google cannot sort them by start date, so the Actor checks at most this many per target (most recently shown first) and stops. Checking is free for you; 1,000 ads take about 30 seconds. 0 = check everything. Default 2000.",
            "default": 2000
          },
          "maxRequestsPerMinute": {
            "title": "Max requests per minute",
            "minimum": 5,
            "maximum": 600,
            "type": "integer",
            "description": "Request throttle, 5-600. Default 50. Without a proxy keep it around 50.",
            "default": 50
          },
          "maxRetries": {
            "title": "Max retries per request",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Retries per request on rate limits or network errors, 0-10. Default 5. Each retry uses a fresh session (and proxy IP, if enabled). Backoff is short and jittered (about 3, 6, 12, 24, 30 s) and respects Retry-After; in total the Actor waits at most 90 s per run on Google rate limits, then tries each request once.",
            "default": 5
          },
          "requestTimeoutSecs": {
            "title": "Request timeout (seconds)",
            "minimum": 5,
            "maximum": 120,
            "type": "integer",
            "description": "Timeout per HTTP request in seconds, 5-120. Default 30.",
            "default": 30
          },
          "maxRunSeconds": {
            "title": "Max run time (seconds)",
            "minimum": 0,
            "maximum": 86400,
            "type": "integer",
            "description": "Stop starting new work after this many seconds and return what was collected so far, plus an 'error' row for each target that was cut short or skipped. 0 (default) = automatic: on Apify the Actor wraps up 15% (20-60 s) before the run timeout, so run-sync callers like n8n or Make (timeout 280-300 s) always get an answer instead of a timed-out run. Rows already delivered stay billed; error rows are free.",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Proxy settings. Default {\"useApifyProxy\": true}, recommended so sessions can rotate on rate limits. If you run without a proxy on Apify and Google keeps answering 429, the Actor switches to Apify Proxy by itself (unless you set useApifyProxy to false).",
            "default": {
              "useApifyProxy": 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}