{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Scraper | from $0.60/1K Ads",
    "description": "Scrape the Google Ads Transparency Center by domain, advertiser ID or name: every ad with format, first and last shown dates, preview, and for EU-served ads impressions per country and platform. Plain HTTP, residential proxies, check 1,000 domains in one run.",
    "version": "0.1",
    "x-build-id": "5obmVKItFdHbah8tn"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/alexmorain~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-alexmorain-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/alexmorain~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-alexmorain-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/alexmorain~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-alexmorain-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": {
          "domains": {
            "title": "Website domains",
            "type": "array",
            "description": "Websites whose ads you want, one per line: <code>nike.com</code>, <code>decathlon.fr</code>. A full URL works too, only the domain is kept. Google matches the domain the ads point to, across every advertiser account that runs them (a big brand often has several).",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Google advertiser IDs like <code>AR16735076323512287233</code>, or the advertiser page URL from adstransparency.google.com. Use them to target one exact verified account rather than everything pointing to a domain.",
            "items": {
              "type": "string"
            }
          },
          "searchTerms": {
            "title": "Advertiser names",
            "type": "array",
            "description": "Advertiser names as you would type them in the Transparency Center search box: <code>Supercell</code>. Each name is matched to the verified advertiser with the most ads whose name contains it; the log lists the other matches with their IDs so you can pin one in Advertiser IDs. A name that looks like a domain (<code>temu.com</code>) is searched as a domain.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Transparency Center URLs",
            "type": "array",
            "description": "Pages copied from adstransparency.google.com: an advertiser page, a domain search (<code>?domain=nike.com&region=US</code>) or a single ad (<code>/advertiser/AR…/creative/CR…</code>). The <code>region</code> in the URL is kept for that URL. A single ad URL always comes with its details.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Only ads shown in these countries: two-letter codes like <code>US</code>, <code>GB</code>, <code>FR</code>, or names in English. Leave empty for all countries. With several countries each one is searched on its own and every ad comes out once, tagged with the first country it was found in.",
            "items": {
              "type": "string"
            }
          },
          "startDate": {
            "title": "Shown from",
            "type": "string",
            "description": "Only ads shown on or after this date. Leave empty for no lower bound."
          },
          "endDate": {
            "title": "Shown until",
            "type": "string",
            "description": "Only ads shown on or before this date. Leave empty for no upper bound."
          },
          "adFormats": {
            "title": "Ad formats",
            "type": "array",
            "description": "Only these formats. Leave empty for all. Text ads are Google Search ads; Google shows them as an image of the ad, so their text is in the preview image, not in a field.",
            "items": {
              "type": "string",
              "enum": [
                "TEXT",
                "IMAGE",
                "VIDEO"
              ],
              "enumTitles": [
                "Text",
                "Image",
                "Video"
              ]
            }
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Only ads shown on these Google platforms. Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "GOOGLE_SEARCH",
                "YOUTUBE",
                "GOOGLE_SHOPPING",
                "GOOGLE_PLAY",
                "GOOGLE_MAPS"
              ],
              "enumTitles": [
                "Google Search",
                "YouTube",
                "Google Shopping",
                "Google Play",
                "Google Maps"
              ]
            }
          },
          "maxAdsPerTarget": {
            "title": "Max ads per target",
            "minimum": 0,
            "type": "integer",
            "description": "Stop each domain, advertiser or name after this many ads, <b>per country</b> when you list several. Set <code>0</code> for no cap: a big brand can hold 100,000 ads. Google lists the most recently shown ads first.",
            "default": 100
          },
          "includeDetails": {
            "title": "Include details",
            "type": "boolean",
            "description": "One extra lookup per ad, priced as a detailed ad. Adds every variant of the ad, each country where it ran with its last shown date, and <b>for ads served in the EU</b> (Digital Services Act data): first and last shown date per country, impressions per country and per platform (Search, YouTube, Shopping, Play, Maps) as ranges, and the product category of Shopping ads. Outside the EU Google publishes the countries and last shown dates only.",
            "default": false
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "all",
              "new-only",
              "check"
            ],
            "type": "string",
            "description": "<b>All ads</b> returns every ad the search finds, on every run.<br><br><b>New ads only</b> keeps a persistent registry of the ads previous runs returned and charged, and returns only ads never returned before: schedule it daily to be told when a competitor launches something new. Once a run has read a search to its end, later runs stop as soon as they reach ads last shown before that run (minus 3 days of margin for Google's indexing delay), so a quiet day costs little more than the start fee.<br><br><b>Check</b> returns one line per domain or advertiser (and per country) instead of ads: does it advertise on Google, Google's range for its ad count, when its latest ad was last shown, which advertiser runs it. One request each, priced per line, made for qualifying long lists of companies.",
            "default": "all"
          },
          "advertisersPerSearchTerm": {
            "title": "Advertisers per name",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many matching advertisers to take for each name in Advertiser names, the ones with the most ads first.",
            "default": 1
          },
          "registryKey": {
            "title": "Registry key (New ads only)",
            "type": "string",
            "description": "By default the registry is tied to the exact targets, countries and filters, so changing any of them starts a fresh one. Set your own key to keep one registry while you edit the list."
          },
          "webhookUrl": {
            "title": "Webhook URL",
            "type": "string",
            "description": "If set, the Actor POSTs a small JSON summary to this URL at the end of the run, <b>only when at least one item was returned</b>: <code>actor</code>, <code>runId</code>, <code>mode</code>, <code>items</code>, <code>searches</code>. With New ads only and a daily schedule, that is a push notification when a competitor launches ads.<br><br>Use the final URL: a redirect is not followed, except a 307 or 308, which gets the same POST once. An unreachable webhook is logged as a warning and never fails the run. Stored encrypted, since a webhook URL often carries its own access token."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Leave as is. Google lets one IP make about 100 requests, then answers with a captcha for a quarter of an hour or more, so the Actor spreads requests over many residential IPs and rotates at the first refusal. The per-ad price is the same whatever you choose.<br><br>With the plain Apify proxy (<code>{\"useApifyProxy\": true}</code>, typical in API calls) it starts on datacenter IPs and <b>switches to residential by itself</b> when Google keeps refusing. If you pick your own proxy URLs, the Actor keeps exactly what you chose.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}