{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Transparency Center Scraper (LatAm-ready)",
    "description": "Extract ads from the Google Ads Transparency Center by brand, advertiser ID or domain. Filter by country (CO, MX, BR, AR, CL, PE presets or any country), date range and format. Monitor mode returns only new ads. Optional full creative details, ad text, YouTube IDs and advertiser profiles. No login.",
    "version": "0.2",
    "x-build-id": "djddLWYkwAZGV6YLz"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/jgapis~google-ads-transparency-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-jgapis-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/jgapis~google-ads-transparency-scraper/runs": {
      "post": {
        "operationId": "runs-sync-jgapis-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/jgapis~google-ads-transparency-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-jgapis-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": {
          "searchTerms": {
            "title": "Search terms (brand / advertiser name)",
            "type": "array",
            "description": "Brand or advertiser names, e.g. \"bancolombia\". Each term is resolved to the best-matching advertiser(s) in the Transparency Center (the ones with the most ads first).",
            "items": {
              "type": "string"
            }
          },
          "advertiserIds": {
            "title": "Advertiser IDs",
            "type": "array",
            "description": "Exact advertiser IDs (start with \"AR\"), copied from the advertiser URL, e.g. AR12885191334436012033.",
            "items": {
              "type": "string"
            }
          },
          "domains": {
            "title": "Domains",
            "type": "array",
            "description": "Return ads that point to these domains, e.g. \"liverpool.com.mx\". Protocol, www. and paths are stripped automatically.",
            "items": {
              "type": "string"
            }
          },
          "maxAdvertisersPerSearchTerm": {
            "title": "Max advertisers per search term",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "How many matching advertisers to include for each search term (sorted by number of ads).",
            "default": 1
          },
          "regions": {
            "title": "Regions (countries where the ad was shown)",
            "type": "array",
            "description": "ISO country codes (CO, MX, BR, AR, CL, PE, US, ES, ...) or presets LATAM_CORE (CO, MX, BR, AR, CL, PE) and LATAM_ALL (19 Latin American countries). Leave empty or use \"anywhere\" for all regions.",
            "items": {
              "type": "string"
            }
          },
          "startDate": {
            "title": "Shown from (date)",
            "type": "string",
            "description": "Only ads shown on or after this date (YYYY-MM-DD). The Transparency Center only serves date-filtered data for roughly the last 12 months. If only an end date is set, the start defaults to 30 days earlier."
          },
          "endDate": {
            "title": "Shown until (date)",
            "type": "string",
            "description": "Only ads shown on or before this date (YYYY-MM-DD). Defaults to today when a start date is set."
          },
          "format": {
            "title": "Ad format",
            "enum": [
              "ALL",
              "TEXT",
              "IMAGE",
              "VIDEO"
            ],
            "type": "string",
            "description": "Filter by creative format.",
            "default": "ALL"
          },
          "maxResults": {
            "title": "Max ads per query",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Maximum number of ads to scan for each search term / advertiser ID / domain. Results come newest first (by last shown date).",
            "default": 100
          },
          "includeDetails": {
            "title": "Include full creative details",
            "type": "boolean",
            "description": "Fetch every variation of each ad plus per-country first/last shown dates (and impression ranges where Google publishes them, mainly EU). Charged per ad as \"Full creative detail\".",
            "default": false
          },
          "extractAdText": {
            "title": "Extract text-ad copy and YouTube video IDs",
            "type": "boolean",
            "description": "Only used with full details. For TEXT and VIDEO ads, also reads the ad preview to get headline, display URL, description, sitelinks and the YouTube video ID (best effort, no extra charge).",
            "default": true
          },
          "includeAdvertiserProfile": {
            "title": "Include advertiser profile",
            "type": "boolean",
            "description": "Add the advertiser's verified/legal name, country and verification status. Fetched once per advertiser per run and charged once per advertiser.",
            "default": false
          },
          "excludeLikelyIndividuals": {
            "title": "Exclude advertisers that look like private individuals",
            "type": "boolean",
            "description": "Every ad is flagged with advertiserLikelyIndividual (a name-based heuristic). Turn this on to drop those ads entirely, e.g. for GDPR / LGPD / Ley 1581 compliance.",
            "default": false
          },
          "monitorMode": {
            "title": "Monitor mode (only new ads)",
            "type": "boolean",
            "description": "Remembers ad IDs already returned for the same query + filters (in a named key-value store) and outputs only ads that are new since the previous run. The first run returns everything it scans. Ideal with Apify Schedules.",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor name (optional)",
            "type": "string",
            "description": "Optional label to keep separate monitoring states for the same query (e.g. per client)."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Apify Proxy (datacenter) is ON by default: in platform tests, runs without a proxy were throttled by Google (HTTP 429 / CAPTCHA). Datacenter proxy is included in all Apify plans; switch to RESIDENTIAL only if you still see blocks.",
            "default": {
              "useApifyProxy": true
            }
          },
          "residentialFallback": {
            "title": "Switch to residential proxy if blocked",
            "type": "boolean",
            "description": "If Google keeps blocking the datacenter proxy (3 consecutive HTTP 429/CAPTCHA responses), automatically switch to Apify RESIDENTIAL proxy for the rest of the run. Ignored when no Apify Proxy is used.",
            "default": true
          },
          "maxConcurrency": {
            "title": "Max concurrent requests",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of requests in flight at once (details and previews are fetched in parallel).",
            "default": 4
          },
          "requestsPerSecond": {
            "title": "Max requests per second",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Global rate limit (requests per second). Google blocks IPs that go too fast (HTTP 429 / CAPTCHA page); 1 req/s without proxy is a safe default. With Apify Proxy you can raise it.",
            "default": 1
          },
          "maxRetries": {
            "title": "Max retries per request",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Retries with exponential backoff (2s, 4s, 8s... up to 90s) on network errors, HTTP 429 and 5xx. On 429 the whole Actor pauses and slows down automatically.",
            "default": 6
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}