{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Center Scraper",
    "description": "Scrape every ad an advertiser runs on Google Search, YouTube, Display, Shopping, Maps and Play from the Google Ads Transparency Center. Extract creative IDs, formats, image URLs, YouTube video IDs, first & last shown dates and regions. Search by brand, domain or advertiser ID. No login or API key.",
    "version": "0.1",
    "x-build-id": "J5jeRvD4iIhgixB03"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/jmlp~google-ads-transparency-center-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-jmlp-google-ads-transparency-center-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/jmlp~google-ads-transparency-center-scraper/runs": {
      "post": {
        "operationId": "runs-sync-jmlp-google-ads-transparency-center-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/jmlp~google-ads-transparency-center-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-jmlp-google-ads-transparency-center-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": {
          "searchTerms": {
            "title": "Brand names",
            "type": "array",
            "description": "Brand or company names to look up, e.g. 'Nike' or 'Booking.com'. Each is resolved to the largest advertiser Google matches, by name and by the brand's own domain - searching 'nike' finds Nike Retail BV and its ~100,000 ads rather than the 34-ad Bulgarian advertiser called 'Nikena', which is all Google's name search returns. The log lists the other matches and their advertiser ids, so you can pin a different one if the wrong company was picked.",
            "items": {
              "type": "string"
            }
          },
          "domains": {
            "title": "Advertiser domains",
            "type": "array",
            "description": "Verified advertiser domains, e.g. nike.com. More precise than a brand name when several companies share one.",
            "items": {
              "type": "string"
            }
          },
          "domain": {
            "title": "Advertiser domain (single)",
            "type": "string",
            "description": "A single advertiser domain."
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Advertiser ids like AR16735076323512287233 - the AR value in a Transparency Center URL. The most precise input: nothing has to be resolved, so nothing can resolve to the wrong company.",
            "items": {
              "type": "string"
            }
          },
          "advertiserId": {
            "title": "Advertiser ID (single)",
            "type": "string",
            "description": "A single advertiser id. Not needed when a brand name, domain or URL is given above."
          },
          "transparencyUrls": {
            "title": "Transparency Center URLs",
            "type": "array",
            "description": "Full advertiser URLs copied from the browser, e.g. https://adstransparency.google.com/advertiser/AR16735076323512287233?region=GB. Each URL brings its own region and platform; the settings below fill in whatever a URL does not carry.",
            "items": {
              "type": "string"
            }
          },
          "transparencyUrl": {
            "title": "Transparency Center URL (single)",
            "type": "string",
            "description": "Paste a single advertiser URL. Its region and platform take precedence over the settings below."
          },
          "regions": {
            "title": "Regions",
            "type": "array",
            "description": "2-letter country codes, e.g. US, GB, DE. Leave empty to cover every region an ad ran in. Listing several scrapes each one as a separate job, which is also how this actor parallelises - but note the same ad appears under every region it ran in, so the totals overlap. Duplicates are removed before anything is written.",
            "items": {
              "type": "string"
            }
          },
          "region": {
            "title": "Region (single)",
            "type": "string",
            "description": "A single 2-letter country code, used when Regions above is empty."
          },
          "platform": {
            "title": "Platform",
            "enum": [
              "all",
              "search",
              "youtube",
              "display",
              "shopping",
              "maps",
              "play"
            ],
            "type": "string",
            "description": "Limit results to one Google surface. Leave as 'All platforms' for everything. Note that an ad can run on several surfaces at once, so the per-platform counts add up to more than the advertiser's total.",
            "default": "all"
          },
          "minDate": {
            "title": "Ran on or after",
            "type": "string",
            "description": "YYYY-MM-DD. Keeps ads that were still running on or after this date. Google's endpoint has no date filter, so this is applied to the dates in the results - it reduces what you are charged for, not how much is fetched, though the run does stop early once it is clearly past the window."
          },
          "maxDate": {
            "title": "Started on or before",
            "type": "string",
            "description": "YYYY-MM-DD. Keeps ads that first ran on or before this date. Combined with the field above it selects ads whose run overlaps the window."
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Google blocks an IP that sends too many requests, so a proxy is strongly recommended for large runs. Datacenter is usually enough here - unlike Meta, these endpoints do not require residential IPs.",
            "default": {
              "useApifyProxy": true
            }
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many jobs run in parallel. A job is one advertiser in one region. Google paginates a single advertiser strictly sequentially and offers no way to split that walk, so this only speeds up runs that cover several advertisers or several regions - one advertiser in one region always runs on one worker.",
            "default": 4
          },
          "maxAds": {
            "title": "Max ads",
            "minimum": 1,
            "type": "integer",
            "description": "Stop after this many unique ads, counted globally across every advertiser and region. The crawl terminates as soon as the cap is hit, so this caps both runtime and cost. Clear it to scrape everything with no limit."
          },
          "maxPages": {
            "title": "Max pages per job",
            "minimum": 1,
            "type": "integer",
            "description": "Safety cap while testing, applied to each job separately. One page is up to 100 ads. Empty = all."
          },
          "fetchAdDetails": {
            "title": "Fetch region breakdown and all variants",
            "type": "boolean",
            "description": "Adds the list of regions each ad ran in, the date it last ran in each, and every creative variant. This costs ONE EXTRA REQUEST PER AD: an advertiser that takes 100 requests to list takes 10,000 with this on. Leave it off unless you need the region detail, and pair it with a low Max ads while testing.",
            "default": false
          },
          "resolveMedia": {
            "title": "Resolve YouTube video IDs",
            "type": "boolean",
            "description": "For video ads, fetches the preview and extracts the YouTube video id so you can open the actual video. Also one extra request per ad, and it only succeeds for ads that really are YouTube videos - display video ads have no public URL.",
            "default": false
          },
          "pageSize": {
            "title": "Page size",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Ads per request. Google rejects anything above 100 by returning an empty response - measured - so values are clamped to 100, which is also the fastest setting.",
            "default": 100
          },
          "delayMs": {
            "title": "Delay between pages (ms)",
            "minimum": 0,
            "type": "integer",
            "description": "Milliseconds to sleep between requests. Google answers a page in roughly 300-800 ms, which is the real floor. Raise this if the log reports blocked jobs.",
            "default": 500
          },
          "raw": {
            "title": "Raw output",
            "type": "boolean",
            "description": "Push records without the null-filling and key ordering of the fixed output schema. Field names are the same.",
            "default": false
          },
          "proxyRotations": {
            "title": "Proxy rotation attempts",
            "minimum": 1,
            "maximum": 6,
            "type": "integer",
            "description": "If a job is refused, the actor mints a new proxy session and retries this many times.",
            "default": 3
          },
          "resume": {
            "title": "Checkpoint progress",
            "type": "boolean",
            "description": "Save progress every ~30s so a run that gets migrated or restarted by the platform picks up where it stopped, without duplicating anything. No effect on fresh runs.",
            "default": true
          },
          "continueFromLastRun": {
            "title": "Continue from last run",
            "type": "boolean",
            "description": "If your previous run with the same input was interrupted, blocked, or stopped because it hit Max ads, scrape only what it missed - picking up from the exact page it had reached. Note the earlier ads stay in THAT run's dataset, so this run's dataset contains only the remainder, and remember to raise Max ads or the budget will already be spent. Leave off to always get a complete dataset in one place.",
            "default": false
          },
          "impersonate": {
            "title": "TLS fingerprint",
            "type": "string",
            "description": "Which browser TLS fingerprint to present. This matters more than it looks: Google refuses several of them outright, serving an 'unusual traffic' page on the very first request. chrome131, chrome124, firefox144 and safari260 were all measured working; chrome136 and newer Chrome builds were all refused. If a run is blocked immediately, the actor already retries the others automatically - set this only to pin one.",
            "default": "chrome131"
          },
          "proxySessionId": {
            "title": "Proxy session id",
            "type": "string",
            "description": "Pin a specific exit IP, for reproducing a run while debugging. Ignored when scraping several jobs or with Max concurrency above 1."
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}