{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Scraper (Ads by Advertiser or Domain)",
    "description": "Google Ads Transparency Center ads by brand, domain or advertiser ID: region, platform, format and date filters, image and preview links, days shown, optional per-country details. No proxy, no login. $0.30 per 1,000 ads.",
    "version": "0.1",
    "x-build-id": "3OfJwRAROL3VgrGnQ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/praguedatalab~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-praguedatalab-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/praguedatalab~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-praguedatalab-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/praguedatalab~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-praguedatalab-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": "Brands, domains or advertiser IDs",
            "type": "array",
            "description": "One search per line. A domain (<code>nike.com</code>) returns the ads that point to that website, whoever pays for them. An advertiser ID (<code>AR18378488041124659201</code>) returns the ads of that advertiser. A brand name (<code>Nike</code>) is matched to the advertisers with the most ads (see maxAdvertisersPerQuery). Page URLs of the Transparency Center and of websites work too.",
            "items": {
              "type": "string"
            }
          },
          "domains": {
            "title": "Domains",
            "type": "array",
            "description": "Websites whose ads you want, one per line, for example <code>adidas.com</code>. Same as putting them in the first field.",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Advertiser IDs (<code>AR</code> followed by 20 digits), one per line. You find them in the advertiser page URL of the Transparency Center.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Transparency Center URLs",
            "type": "array",
            "description": "Advertiser pages, ad pages or domain searches copied from <code>adstransparency.google.com</code>. The region, platform, format and date parameters of the URL are used for that URL.",
            "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": "<code>ads</code> saves the ads (event: ad). <code>advertisers</code> saves the advertisers instead (name, legal name, country, identity verified, approximate number of ads).",
            "default": "ads"
          },
          "region": {
            "title": "Region",
            "type": "string",
            "description": "Country where the ads were shown: a two-letter code (<code>US</code>, <code>DE</code>, <code>FR</code>) or an English country name. <code>anywhere</code> searches every country. Default <code>US</code>. Alias: <code>country</code>."
          },
          "regions": {
            "title": "Several regions",
            "type": "array",
            "description": "More than one country, one per line. Each is searched separately (the same ad in two countries gives two rows, with its own <code>region</code>).",
            "items": {
              "type": "string"
            }
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Keep only ads shown on these Google platforms: <code>search</code>, <code>youtube</code>, <code>shopping</code>, <code>maps</code>, <code>play</code> (the spellings <code>google_search</code>, <code>google_maps</code>… work too). Empty means all platforms.",
            "items": {
              "type": "string"
            }
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "ALL",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Keep only text, image or video ads."
          },
          "startDate": {
            "title": "Shown from",
            "type": "string",
            "description": "Only ads shown on or after this day, YYYY-MM-DD. Alias: <code>dateFrom</code>."
          },
          "endDate": {
            "title": "Shown until",
            "type": "string",
            "description": "Only ads shown on or before this day, YYYY-MM-DD. Alias: <code>dateTo</code>."
          },
          "maxAdsPerSearch": {
            "title": "Maximum ads per search",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Ads saved for each query and each region (100 ads per request, newest first). <code>0</code> means as many as exist. You pay per ad saved. Alias: <code>maxResults</code>. Default 100."
          },
          "maxItems": {
            "title": "Maximum results in total",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Stops the run after this many rows (ads or advertisers), all searches together. You can also set a maximum cost per run in the run options."
          },
          "maxAdvertisersPerQuery": {
            "title": "Advertisers per brand name",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "A brand name such as <code>Nike</code> matches many advertisers. The ones with the most ads are kept, up to this number.",
            "default": 5
          },
          "includeDetails": {
            "title": "Include ad details",
            "type": "boolean",
            "description": "Adds the variations of each ad, the countries where it ran with first and last day and the range of times shown, the topic Google gave it and who paid for it. One extra request per ad, so the run is slower. No extra charge.",
            "default": false
          },
          "detailConcurrency": {
            "title": "Detail requests in parallel",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "How many detail requests may be in flight at once. Requests are spaced out anyway to stay under Google's rate limit.",
            "default": 2
          },
          "onlyNewAds": {
            "title": "Only ads not seen before",
            "type": "boolean",
            "description": "Skip ads that an earlier run with the same monitor store already saved. Use it with a schedule to get only the new ads of a brand each day.",
            "default": false
          },
          "monitorStoreName": {
            "title": "Monitor store name",
            "type": "string",
            "description": "Name of the key-value store that remembers the ads already seen (used by onlyNewAds). Letters, digits and dashes, at least 3.",
            "default": "google-ads-transparency-seen"
          },
          "includeRawData": {
            "title": "Include raw data",
            "type": "boolean",
            "description": "Adds the untouched answer of Google for each ad in the <code>raw</code> field (keys are field numbers).",
            "default": false
          },
          "urlsFromFile": {
            "title": "URL of a text file with searches",
            "type": "string",
            "description": "Link to a plain text file with one brand, domain, advertiser ID or URL per line. Lines starting with # are ignored."
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Not needed: the endpoint answers requests from Apify servers. Turn on the Apify proxy only if Google asks for a captcha (the run then says so).",
            "default": {
              "useApifyProxy": false
            }
          },
          "searchQuery": {
            "title": "Search query (alias)",
            "type": "string",
            "description": "A keyword, domain or advertiser ID. Same as one line in the first field."
          },
          "platform": {
            "title": "Platform (alias)",
            "enum": [
              "",
              "google_search",
              "youtube",
              "google_shopping",
              "google_maps",
              "google_play"
            ],
            "type": "string",
            "description": "One platform. Same as the Platforms field."
          },
          "maxResults": {
            "title": "Maximum results (alias)",
            "minimum": 0,
            "maximum": 100000,
            "type": "integer",
            "description": "Same as Maximum ads per search. <code>0</code> means as many as exist."
          },
          "dateFrom": {
            "title": "Date from (alias)",
            "type": "string",
            "description": "Same as Shown from."
          },
          "dateTo": {
            "title": "Date to (alias)",
            "type": "string",
            "description": "Same as Shown until."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}