{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Scraper: Ads, Text and Reach",
    "description": "Google Ads Transparency scraper at $0.50 per 1,000 ads, with ad text, impressions per country and platform, and targeting included. Search by brand, website, advertiser ID or Transparency Center URL; filter by country, platform, format and dates; monitor only new ads.",
    "version": "0.1",
    "x-build-id": "P8pbCclfeGYpIZuYb"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/agenttoolworks~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-agenttoolworks-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/agenttoolworks~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-agenttoolworks-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/agenttoolworks~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-agenttoolworks-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",
            "type": "array",
            "description": "Brand or advertiser names, one per line, each its own search. Google has no keyword search of ad text: the Actor finds the advertisers whose name contains the word ('nike' finds 'Nike, Inc.') and returns their ads. A brand that advertises under its company's name ('temu' advertises as Whaleco Inc.) is read through its own website when Google suggests one (temu.com), and the run summary says so. For an exact brand, use Websites.",
            "items": {
              "type": "string"
            }
          },
          "domains": {
            "title": "Websites",
            "type": "array",
            "description": "Advertiser websites, one per line (nike.com): every ad that points to the site, whichever Google advertiser account ran it (brands often advertise through agencies and regional companies).",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Google advertiser IDs, one per line: AR followed by 20 digits, as in the Transparency Center's address bar (adstransparency.google.com/advertiser/AR16735076323512287233). The Actor reads that advertiser's ads directly.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Transparency Center URLs",
            "type": "array",
            "description": "Paste what you see in adstransparency.google.com: a search by website (?region=FR&domain=nike.com), an advertiser's page (/advertiser/AR...) or one ad's page (/advertiser/AR.../creative/CR...). The page's region (or anywhere), platform, format and dates are kept, the date menu's presets included (the last 7 or 30 days, today, yesterday, in Pacific Time as on the page), and win over the filters below. A URL whose filter cannot be read is left out with a note, never searched without it.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "Where the ads were shown: two-letter codes (US, FR, DE...) or English names (United States, India), in any case. Empty means anywhere. Impressions per country and per platform are published by Google for ads shown in the EU.",
            "items": {
              "type": "string"
            }
          },
          "platforms": {
            "title": "Platforms",
            "type": "array",
            "description": "Only ads shown on these Google platforms. Google's platform filter only covers ads shown since 4 September 2023, and takes one platform at a time: with several, each is its own search, up to the max ads below each. Empty (the default) searches every platform at once, older ads included.",
            "items": {
              "type": "string",
              "enum": [
                "SEARCH",
                "YOUTUBE",
                "MAPS",
                "PLAY",
                "SHOPPING"
              ],
              "enumTitles": [
                "Google Search",
                "YouTube",
                "Google Maps",
                "Google Play",
                "Google Shopping"
              ]
            }
          },
          "formats": {
            "title": "Formats",
            "type": "array",
            "description": "Only ads of these formats. Empty (the default) keeps every format.",
            "items": {
              "type": "string",
              "enum": [
                "TEXT",
                "IMAGE",
                "VIDEO"
              ],
              "enumTitles": [
                "Text",
                "Image",
                "Video"
              ]
            }
          },
          "startDate": {
            "title": "Shown from",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Optional, YYYY-MM-DD. Only ads shown on or after this day."
          },
          "endDate": {
            "title": "Shown until",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "type": "string",
            "description": "Optional, YYYY-MM-DD. Only ads shown on or before this day."
          },
          "maxAdsPerSearch": {
            "title": "Max ads per search",
            "minimum": 1,
            "maximum": 5000,
            "type": "integer",
            "description": "Stop after this many ads for each brand, website, advertiser or URL (and each platform, when you pick several). Google lists the most recently shown ads first. You are charged per ad returned.",
            "default": 100
          },
          "includeDetails": {
            "title": "Include ad text, reach and targeting",
            "type": "boolean",
            "description": "One more request per ad, at no extra charge: impressions per country and in total, the platforms that showed it (Search, YouTube, Maps, Play, Shopping, for ads shown in the EU), first and last day shown per country, the targeting criteria used, and the headline and description of text ads where Google renders them. Off gives a faster list of creatives.",
            "default": true
          },
          "maxAdvertisers": {
            "title": "Advertiser records per search",
            "minimum": 0,
            "maximum": 20,
            "type": "integer",
            "description": "Optional, off by default. Also return up to this many advertiser records per search (ID, name, country, how many ads Google holds for it): stored in the run's key-value store (record ADVERTISERS), not in the ads dataset, and charged per advertiser. For a brand search it also widens the search to that many advertisers named like the brand (one by default, the biggest).",
            "default": 0
          },
          "onlyNewAds": {
            "title": "Only new ads",
            "type": "boolean",
            "description": "For scheduled runs: return and charge only the ads this monitor has not returned before, per search. The ads already returned are kept in a key-value store of your account named ads-transparency-monitor-<monitor name>. The first run returns everything it reads; the run summary says how many ads were new and how many already seen.",
            "default": false
          },
          "monitorName": {
            "title": "Monitor name",
            "type": "string",
            "description": "Names the memory of Only new ads, so separate schedules keep separate lists (letters, digits and hyphens). Empty means 'default'."
          },
          "proxy": {
            "title": "Proxy",
            "enum": [
              "auto",
              "residential",
              "none"
            ],
            "type": "string",
            "description": "Google refuses many requests from the Apify cloud's shared IPs, so the Actor reads through Apify Proxy, at no extra charge to you. Auto: datacenter IPs, and residential ones after two refusals in a row. Residential: residential IPs from the start. None: no proxy (expect refusals on Apify).",
            "default": "auto"
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}