{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Scraper - Competitor Ad Creatives",
    "description": "Scrape every ad creative an advertiser runs on Google Search, YouTube, Shopping, Maps and Play. Search by domain, advertiser ID or brand name. Each ad ships with its format, first/last shown dates, days shown, every country it ran in, impression ranges and the creative image. No API key.",
    "version": "0.1",
    "x-build-id": "th4pr62dvrdg2L6Dc"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapersdelight~adstransparency-google-creatives-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapersdelight-adstransparency-google-creatives-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/scrapersdelight~adstransparency-google-creatives-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapersdelight-adstransparency-google-creatives-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/scrapersdelight~adstransparency-google-creatives-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapersdelight-adstransparency-google-creatives-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": {
          "domains": {
            "title": "Advertiser domains",
            "type": "array",
            "description": "The websites the ads point at, e.g. `nike.com`. This is the easiest way in: you do not need to know Google's advertiser ID. Use the bare registered domain (`https://`, `www.` and any path are stripped for you). One advertiser domain can map to several legal advertiser entities and all of them are returned.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Google Ads Transparency advertiser IDs, e.g. `AR16735076323512287233` — the `AR…` segment of an adstransparency.google.com advertiser URL. Exact and unambiguous; use it when a domain is shared by several advertisers. All the IDs you list are queried in a single request.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "advertiserNames": {
            "title": "Brand names",
            "type": "array",
            "description": "Advertiser names to look up, e.g. `Progressive Insurance`. Each name is resolved to real advertiser IDs through Google's own suggestion endpoint and the top matches are then scraped. Use `Max advertisers per brand name` to control how many entities each name expands to.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Only return creatives that ran in these countries, as ISO 3166-1 alpha-2 codes (`US`, `GB`, `DE`, `JP`). Leave empty for every country. This is a server-side filter, so it makes the scrape cheaper rather than just trimming the output. Codes that are not valid alpha-2 are ignored with a warning.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "format": {
            "title": "Ad format",
            "enum": [
              "any",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Restrict to one Google ad format. `TEXT` is the search/text ad (Google archives these as a rendered screenshot of the ad, sitelinks included), `IMAGE` is a display or shopping creative, `VIDEO` is a YouTube ad. Google's API accepts only one format at a time, so `any` is the way to get the full mix.",
            "default": "any"
          },
          "includeDetails": {
            "title": "Enrich each creative with its detail record",
            "type": "boolean",
            "description": "On by default, and it is where most of the value is: one extra request per creative adds every country the ad ran in with per-country first/last-shown dates, the impression range, the Google Search / Shopping / YouTube / Maps / Play split, every archived rendition of the creative, and — for search ads that still have a live preview — the ad's own headline and description text. Switch it off for a roughly 2x faster, list-only scrape.",
            "default": true
          },
          "maxItems": {
            "title": "Max creatives (total)",
            "minimum": 0,
            "type": "integer",
            "description": "Stop after this many creatives across all targets. Large advertisers run tens of thousands of ads, so the default is deliberately modest — raise it once you know the scope you want. 0 = no limit.",
            "default": 200
          },
          "maxItemsPerTarget": {
            "title": "Max creatives per target",
            "minimum": 0,
            "type": "integer",
            "description": "Cap the creatives taken from any single domain / advertiser-ID set / brand name, so one enormous advertiser cannot eat the whole run. 0 = no per-target cap (the total cap still applies).",
            "default": 0
          },
          "maxAdvertisersPerName": {
            "title": "Max advertisers per brand name",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many advertiser entities each entry in `Brand names` expands to. A brand often has one advertiser account per market, so 3 picks up the main ones without pulling in every namesake.",
            "default": 3
          },
          "detailConcurrency": {
            "title": "Detail request concurrency",
            "minimum": 1,
            "maximum": 12,
            "type": "integer",
            "description": "How many creative-detail requests run in parallel. Google rate-limits this endpoint per IP (HTTP 429), so raising this without proxy rotation will slow the run down rather than speed it up.",
            "default": 6
          },
          "residentialFallback": {
            "title": "Fall back to residential proxies",
            "type": "boolean",
            "description": "Leave this on. Google rate-limits this endpoint per IP and Apify's shared datacenter range can be sitting on HTTP 429 for hours at a time; when that happens the run automatically switches to residential IPs instead of returning you an empty dataset. Turn it off only if your account must never use residential proxy traffic.",
            "default": true
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify Proxy is on by default and you should leave it on: Google rate-limits this endpoint per IP, and a rotating proxy session per request is what keeps a long run from stalling on HTTP 429. The endpoint itself needs no residential IPs — datacenter is enough.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}