{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Ads Scraper — Live Search Sponsored Ads",
    "description": "Scrape live Google Search sponsored (PPC) ads by keyword, country, city and device: one row per ad with advertiser, ad copy, slot, sitelinks and landing URL, plus a free advertiser share-of-voice summary. Live search ads, not the Ads Transparency Center.",
    "version": "1.0",
    "x-build-id": "mZIyVtWaf2m2cvQOP"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~google-ads-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-google-ads-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/khadinakbar~google-ads-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-google-ads-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/khadinakbar~google-ads-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-google-ads-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",
        "required": [
          "queries"
        ],
        "properties": {
          "queries": {
            "title": "Search keywords",
            "type": "array",
            "description": "Keywords to search on Google. The scraper returns the SPONSORED (paid) ads shown for each keyword, one record per ad. Example: ['car insurance', 'crm software']. This is live SERP ad data, NOT Google Ads Transparency Center creatives — for advertiser creative history use a Transparency Center scraper instead. Free Apify plan runs return up to 40 results per run.",
            "items": {
              "type": "string"
            }
          },
          "countryCode": {
            "title": "Country",
            "enum": [
              "us",
              "gb",
              "ca",
              "au",
              "de",
              "fr",
              "es",
              "it",
              "nl",
              "in",
              "br",
              "mx",
              "jp",
              "ae",
              "sg",
              "za"
            ],
            "type": "string",
            "description": "Two-letter ISO country code that geo-targets the Google search (the gl parameter), e.g. 'us', 'gb', 'de'. Ads are country-specific, so this strongly affects which advertisers appear. Defaults to 'us'. For city-level targeting also set locationName.",
            "default": "us"
          },
          "languageCode": {
            "title": "Language",
            "enum": [
              "en",
              "de",
              "fr",
              "es",
              "it",
              "nl",
              "pt",
              "ja",
              "ar",
              "hi"
            ],
            "type": "string",
            "description": "Two-letter ISO language code for the Google interface and results (the hl parameter), e.g. 'en', 'de', 'fr'. Defaults to 'en'. Set this to the language advertisers in your target country actually bid in, not your own.",
            "default": "en"
          },
          "locationName": {
            "title": "City location (optional)",
            "type": "string",
            "description": "Optional canonical location for city-level ad targeting via Google's uule parameter, e.g. 'New York,New York,United States' or 'London,England,United Kingdom'. Use the exact 'City,Region,Country' form. Leave blank to target the whole country set by countryCode. NOT a latitude/longitude."
          },
          "device": {
            "title": "Device",
            "enum": [
              "desktop",
              "mobile"
            ],
            "type": "string",
            "description": "Whether to fetch the desktop or mobile Google results page. Mobile and desktop often show different ads and ad counts, so pick the surface you want to monitor. Defaults to 'desktop'.",
            "default": "desktop"
          },
          "maxAdsPerQuery": {
            "title": "Max ads per keyword (cost cap)",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Hard cap on how many ads are saved and billed per keyword. This is your cost control: the run charges at most (number of keywords x maxAdsPerQuery) ad-found events — see the Pricing tab for the per-event price. Defaults to 20. A typical results page shows 3-7 ads, so 20 rarely truncates. Range 1-100.",
            "default": 20
          },
          "maxPagesPerQuery": {
            "title": "Pages per keyword",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "How many Google result pages to fetch per keyword. Ads concentrate on page 1, so the default 1 is best for most users; raise it only to capture bottom-of-funnel ads on deeper pages. Range 1-5.",
            "default": 1
          },
          "includeBottomAds": {
            "title": "Include bottom-of-page ads",
            "type": "boolean",
            "description": "Whether to also capture sponsored ads shown at the BOTTOM of the results page, not just the top block. Bottom ads are usually lower-bid competitors. Defaults to true. Set false to monitor only premium top-of-page ad slots.",
            "default": true
          },
          "includeSummaryRows": {
            "title": "Add advertiser share-of-voice rows",
            "type": "boolean",
            "description": "When enabled, the dataset also gets one free summary row per advertiser (recordType 'advertiserSummary'): ads seen, share of all ads, keywords with ads, top-of-page share and average top rank. Summary rows are never billed. The same share-of-voice summary is always written to the OUTPUT record. Defaults to false, so the dataset contains only ad rows.",
            "default": false
          },
          "engine": {
            "title": "Scraping engine",
            "enum": [
              "auto",
              "serpapi",
              "browser"
            ],
            "type": "string",
            "description": "How ads are fetched. 'auto' (recommended) uses the reliable managed search engine when a key is available (built in by default) and falls back to a stealth browser otherwise. 'managed search' forces the managed search API. 'browser' tries a stealth browser first and only falls back to managed search if Google blocks it. Most users should leave this on 'auto'.",
            "default": "auto"
          },
          "serpApiKey": {
            "title": "Own search API key (optional)",
            "type": "string",
            "description": "Optional: bring your own key for the managed Google search API this Actor uses (the provider indicated by this field's name) to run on your own quota and rate limits. Leave blank to use the built-in managed key. This is a credential, not a search term — it is never stored in your output."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}