{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Center Scraper & API",
    "description": "Scrape ads from the Google Ads Transparency Center by brand, domain or advertiser. Get creatives, dates, days active and per-country reach. No login. Independent tool, not affiliated with Google.",
    "version": "1.0",
    "x-build-id": "zBokIqeReaYSCVCK8"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-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/scrapesage~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-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/scrapesage~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-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": {
          "queries": {
            "title": "Brand names or domains",
            "type": "array",
            "description": "Free-text brand names (e.g. \"Nike\", \"HelloFresh\") or websites (e.g. \"nike.com\"). A brand name is matched to advertiser names through the Transparency Center's search, then their ads are scraped; in advertiser mode, a brand name that matches no advertiser is checked as a website instead. A website is looked up as that website: in ad mode the ads that point to it, in advertiser mode the accounts running them.",
            "items": {
              "type": "string"
            }
          },
          "domains": {
            "title": "Domains (exact)",
            "type": "array",
            "description": "Exact domains, e.g. \"nike.com\". In ad mode: every ad that points to that domain, from any advertiser account. In advertiser mode: the advertiser accounts running those ads (a quick way to check whether a list of company websites run Google Ads).",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Specific advertiser IDs (start with \"AR\"). Find these on an advertiser's Transparency Center page URL.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (paste from the website)",
            "type": "array",
            "description": "Paste Ads Transparency Center URLs: advertiser pages, creative pages, or domain search pages. They are parsed automatically.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "resultType": {
            "title": "What to return",
            "enum": [
              "ads",
              "advertisers"
            ],
            "type": "string",
            "description": "\"ads\" returns individual ad creatives. \"advertisers\" returns one summary row per advertiser (approximate ad counts, country, legal name, verified badge) found by brand name, by website or by advertiser ID - ideal for checking whether companies run Google Ads (lead-gen / competitive research).",
            "default": "ads"
          },
          "region": {
            "title": "Region",
            "type": "string",
            "description": "Country to scope results: a two-letter code (e.g. \"US\", \"DE\", \"SG\") or an English country name (e.g. \"Germany\"), or \"ANYWHERE\" for all regions. Note: platform filters only apply to ads shown on/after 2023-09-04.",
            "default": "US"
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Restrict to ads served on specific Google surfaces. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "SEARCH",
                "YOUTUBE",
                "SHOPPING",
                "MAPS",
                "PLAY"
              ],
              "enumTitles": [
                "Google Search",
                "YouTube",
                "Shopping",
                "Maps",
                "Play"
              ]
            },
            "default": []
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "ALL",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Filter by creative format.",
            "default": "ALL"
          },
          "startDate": {
            "title": "Shown after",
            "type": "string",
            "description": "Only ads shown on or after this date (YYYY-MM-DD). Google's Ads Transparency Center keeps the last 12 months of ad dates, so an earlier date starts at the beginning of those 12 months. On its own, it runs up to today."
          },
          "endDate": {
            "title": "Shown before",
            "type": "string",
            "description": "Only ads shown before this date (YYYY-MM-DD). It must fall inside the last 12 months, the only dates Google keeps: a range that ends earlier stops at once and bills nothing. On its own, it covers the 12 months up to this date."
          },
          "maxAdsPerSearch": {
            "title": "Max ads per target",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Maximum ad creatives to collect for each domain/advertiser target.",
            "default": 100
          },
          "maxAdvertisersPerQuery": {
            "title": "Max advertisers per query",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "When resolving a brand-name query, how many of the top matching advertisers to scrape.",
            "default": 5
          },
          "includeDetails": {
            "title": "Fetch full creative details",
            "type": "boolean",
            "description": "Makes one extra request per ad to add what the fast run cannot see: every creative variation (A/B variants), `regionsShown` (every country the ad ran in, with its dates) and, for ads shown in the EU, Google's reach data (times shown per country and per platform) and the audience criteria the advertiser selected. Slower; billed per ad via a separate event.",
            "default": false
          },
          "detailConcurrency": {
            "title": "Detail fetch concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many per-ad detail requests to run in parallel when 'Fetch full creative details' is on. Higher = faster, but more aggressive. Has no effect in fast mode.",
            "default": 6
          },
          "includeAdText": {
            "title": "Include ad text",
            "type": "boolean",
            "description": "Adds the words of each ad where Google's preview holds them: the headline, description and display URL of text ads, the business name of local ads and the product title of Shopping ads (adHeadline, adDescription, adDisplayUrl, adBusinessName, adTextKind, adTextLines). Billed per ad via the separate Ad Text event, only where text is found. Image and video ads keep their words inside the picture, so they get no text and no charge.",
            "default": false
          },
          "onlyNewAds": {
            "title": "Monitor mode: only new ads",
            "type": "boolean",
            "description": "Output only ads not seen in previous runs. Remembers creative IDs across runs in a named key-value store, so a scheduled (daily/weekly) run returns just newly-launched ads, ideal for competitor new-ad alerts. The first run returns everything and seeds the memory.",
            "default": false
          },
          "monitorStoreName": {
            "title": "Monitor store name",
            "type": "string",
            "description": "Name of the key-value store that holds seen creative IDs for monitor mode. Use a distinct name per monitoring target so their histories don't mix.",
            "default": "ads-transparency-monitor"
          },
          "includeRawData": {
            "title": "Include raw API payload",
            "type": "boolean",
            "description": "Attach the raw decoded API objects to each result for debugging.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Residential proxies are recommended for large runs.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "urlsFromFile": {
            "title": "Import URLs from a file",
            "type": "string",
            "description": "Paste a list of URLs (one per line), OR one link to a .txt/.csv file, Google Sheet or Google Drive file containing them. Lets you import many Start URLs at once instead of typing each. Google Sheet/Drive share links are handled automatically."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}