{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Scraper API — Competitor Ads, $0.50/1K",
    "description": "Scrape every ad a company runs on Google (Search, YouTube, Shopping, Maps, Play) from the Ads Transparency Center, by domain, brand or advertiser ID: format, first/last shown, days active, previews; optional countries, impressions, variations and ad text. $0.50 per 1,000 ads, no login.",
    "version": "0.1",
    "x-build-id": "ohhE5UhOQgvrXIxOq"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/sherwood~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-sherwood-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/sherwood~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-sherwood-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/sherwood~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-sherwood-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": "Domains, brands or advertiser IDs",
            "type": "array",
            "description": "What to look up in the Google Ads Transparency Center: a website (nike.com), a brand or company name (Nike), an advertiser ID (AR + 20 digits) or an adstransparency.google.com URL (advertiser page or creative page). Several per run. A single string may hold several entries separated by commas or new lines; a brand name is resolved to its advertisers first.",
            "default": [
              "nike.com"
            ],
            "items": {
              "type": "string"
            }
          },
          "region": {
            "title": "Region",
            "type": "string",
            "description": "Where the ads were shown: a two-letter country code (US, FR, DE), an English country name (France), or ANYWHERE for every country. Countries in the EU also expose impressions and platform data on ad details.",
            "default": "ANYWHERE"
          },
          "adFormat": {
            "title": "Ad format",
            "enum": [
              "ALL",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Keep only text, image or video ads.",
            "default": "ALL"
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Keep only ads shown on these Google surfaces. Empty = all platforms. Google applies platform data to ads shown on or after 2023-09-04.",
            "items": {
              "type": "string",
              "enum": [
                "SEARCH",
                "YOUTUBE",
                "MAPS",
                "PLAY",
                "SHOPPING"
              ],
              "enumTitles": [
                "Google Search",
                "YouTube",
                "Google Maps",
                "Google Play",
                "Google Shopping"
              ]
            },
            "default": []
          },
          "startDate": {
            "title": "Shown on or after",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "YYYY-MM-DD. Keeps the ads whose shown period overlaps the window [startDate, endDate]. Google only keeps the last 12 months of shown dates, so an earlier date starts there. On its own, the window runs to today."
          },
          "endDate": {
            "title": "Shown on or before",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "YYYY-MM-DD. On its own, the window covers the 12 months up to this date."
          },
          "maxAdsPerQuery": {
            "title": "Max ads per query",
            "minimum": 1,
            "type": "integer",
            "description": "Ads collected for each domain, brand or advertiser (40 per page). Large advertisers have tens of thousands.",
            "default": 100
          },
          "maxAds": {
            "title": "Max ads in total",
            "minimum": 1,
            "type": "integer",
            "description": "Hard cap for the whole run, across every query, after de-duplication by creative ID.",
            "default": 1000
          },
          "includeDetails": {
            "title": "Include details (countries, impressions, variations, ad text)",
            "type": "boolean",
            "description": "One extra request per ad: every country the ad ran in with first and last shown dates, impressions range and platform split (published by Google for EU countries), every variation with its preview, the advertiser's legal name, the audience criteria selected, and the ad text, landing page and display domain read from the preview. Charged $0.50 per 1,000 detailed ads on top of the ad itself; never charged when the detail cannot be read.",
            "default": false
          },
          "resultType": {
            "title": "Result type",
            "enum": [
              "ads",
              "advertisers"
            ],
            "type": "string",
            "description": "\"ads\" lists the ads. \"advertisers\" answers 'does this company advertise on Google?' with one item per advertiser account matching each query: name, advertiser ID, country, approximate number of ads, verified badge. Cheap lead qualification: one request per query.",
            "default": "ads"
          },
          "query": {
            "title": "query (alias)",
            "type": "string",
            "description": "Alias of queries: one or several entries separated by commas or new lines. Other accepted aliases: domains, domain, advertiserIds, startUrls, urls, searchTerms."
          },
          "domains": {
            "title": "domains (alias)",
            "type": "array",
            "description": "Alias of queries.",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "advertiserIds (alias)",
            "type": "array",
            "description": "Alias of queries: advertiser IDs (AR + 20 digits).",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "startUrls (alias)",
            "type": "array",
            "description": "Alias of queries: adstransparency.google.com URLs.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify datacenter proxies by default: Google slows an IP down after about ten pages, so the Actor rotates sessions. A residential IP is tried automatically if Google refuses.",
            "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
                  },
                  "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}