{
  "openapi": "3.0.1",
  "info": {
    "title": "Competitor Ads Spy - Google Ads Transparency Center, Creatives",
    "description": "19,782 ads for one advertiser in one region in 31.5 seconds, 244 regions, 63 columns where the most used rivals show 13. Google Ads library scraper for competitor ad creatives: format, surface and policy codes translated, removed ads with the policy that removed them.",
    "version": "0.1",
    "x-build-id": "Nm58ksee5rvMpokg8"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/snow_leo_data~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-snow_leo_data-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/snow_leo_data~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-snow_leo_data-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/snow_leo_data~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-snow_leo_data-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": {
          "advertiserNames": {
            "title": "Brand or advertiser names",
            "type": "array",
            "description": "Brand names to look up in the report, for example \"Nike\" or \"Booking.com\". One brand usually runs several advertiser accounts (Nike has nine in the report, from 9,000 ads down to one), so the actor takes the biggest ones - see maxAdvertisersPerName - instead of guessing.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "domains": {
            "title": "Domains",
            "type": "array",
            "description": "Landing page domains, for example nike.com. A domain covers every advertiser account that sends traffic there, including resellers and affiliates, so it returns far more than a single advertiser id.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Exact advertiser ids from the report, for example AR16735076323512287233.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Report URLs",
            "type": "array",
            "description": "Paste links from adstransparency.google.com. Advertiser, creative, domain and region are read out of the link.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "resultType": {
            "title": "What to return",
            "enum": [
              "ads",
              "advertisers",
              "both",
              "disapproved"
            ],
            "type": "string",
            "description": "ads - ad creatives; advertisers - advertiser accounts behind the brand names; both - advertisers first, then their ads; disapproved - ads Google removed for a policy violation, with the policy, the enforcement means and the decision type. Note on `disapproved`: that report is Google's own global takedown feed, so its rows carry the creative, the policy and the dates, but NO advertiser id or name - they cannot be tied back to one competitor.",
            "default": "ads"
          },
          "regions": {
            "title": "Regions",
            "type": "array",
            "description": "Country codes or names, or \"anywhere\" for the worldwide view. The report is region scoped: nike.com shows 100,000-200,000 ads worldwide but 8,000-9,000 in the US and 400-500 in Japan. Several regions in one run are allowed - each is a separate pass and the same ad found in two of them is delivered once, with both regions listed.",
            "default": [
              "anywhere"
            ],
            "items": {
              "type": "string"
            }
          },
          "adFormats": {
            "title": "Ad formats",
            "type": "array",
            "description": "text, image or video. Leave empty for all three.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "surfaces": {
            "title": "Google surfaces",
            "type": "array",
            "description": "Where the ad was shown: search, youtube, shopping, maps, play. Leave empty for all of them.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "shownAfter": {
            "title": "Last shown on or after",
            "type": "string",
            "description": "YYYY-MM-DD. Keeps ads whose last recorded impression is on or after this date. Applied by the actor after collecting, because the report accepts its own date bounds and then ignores them - measured, see the README."
          },
          "shownBefore": {
            "title": "First shown on or before",
            "type": "string",
            "description": "YYYY-MM-DD. Keeps ads that started running on or before this date."
          },
          "minDaysShown": {
            "title": "Minimum days shown",
            "minimum": 0,
            "type": "integer",
            "description": "Keep only ads that ran at least this many days. A long runner is a tested creative; a one-day ad is usually a test."
          },
          "onlyWithImage": {
            "title": "Only ads with an image",
            "type": "boolean",
            "description": "Keep only creatives that carry a direct image URL.",
            "default": false
          },
          "includeDetails": {
            "title": "Fetch full creative details",
            "type": "boolean",
            "description": "One extra request per ad. Adds every rendering variation, the targeting categories used, age and gender conditions, the product category, per country impression ranges with first and last served dates, the EEA and US breakdowns, the AI-generated content flag and the legal entity name. On by default: without it a row carries 12 fields instead of 22, and the extra columns are the reason to use this Actor. Measured: no extra time on a first run.",
            "default": true
          },
          "detailConcurrency": {
            "title": "Detail threads",
            "minimum": 1,
            "maximum": 16,
            "type": "integer",
            "description": "How many detail requests run at once. Eight is measured as safe; sixteen starts getting rate limited.",
            "default": 8
          },
          "politicalReport": {
            "title": "Political ads report",
            "type": "boolean",
            "description": "Ask the political section of the report instead of the general one. Advertiser rows then carry the regulator id (FEC and the EU equivalents), the declared candidate or ballot measure and the promoter.",
            "default": false
          },
          "onlyNewAds": {
            "title": "Monitor mode: only new or changed ads",
            "type": "boolean",
            "description": "Remembers what earlier runs delivered in a named key-value store and writes only what is new or changed. A daily watch on a competitor then pays for the few new creatives instead of the whole library.",
            "default": false
          },
          "emitUnchanged": {
            "title": "Also emit unchanged ads",
            "type": "boolean",
            "description": "In monitor mode, deliver unchanged ads too, tagged with change_type. Off by default because unchanged rows cost money and say nothing.",
            "default": false
          },
          "maxItems": {
            "title": "Max rows to deliver",
            "minimum": 0,
            "type": "integer",
            "description": "Hard limit on DELIVERED rows, not on rows walked: with filters on, the actor keeps walking until it has this many rows that actually passed. Zero means no limit.",
            "default": 50
          },
          "maxAdsPerTarget": {
            "title": "Max ads per target",
            "minimum": 0,
            "type": "integer",
            "description": "Cap per advertiser, domain or region pass, so one huge advertiser cannot eat the whole run. Zero means no cap.",
            "default": 0
          },
          "maxAdvertisersPerName": {
            "title": "Advertiser accounts per brand name",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "How many advertiser accounts to take for each brand name, biggest first.",
            "default": 3
          },
          "includeHtml": {
            "title": "Include the ad HTML",
            "type": "boolean",
            "description": "Keep the raw HTML snippet of the creative. Off by default: it is the heaviest field and most buyers only need the image URL.",
            "default": false
          },
          "includeRawData": {
            "title": "Include the raw payload",
            "type": "boolean",
            "description": "Attach the untouched response object to every row.",
            "default": false
          },
          "compactOutput": {
            "title": "Compact output",
            "type": "boolean",
            "description": "Drop empty fields and the heavy HTML and variation lists. Useful when the rows go into an AI agent with a token budget.",
            "default": false
          },
          "monitorStoreName": {
            "title": "Monitor memory name",
            "type": "string",
            "description": "Name of the named key-value store that remembers what monitor mode already delivered. Give each watch its own name when you track several competitors, otherwise they share one memory."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}