{
  "openapi": "3.0.1",
  "info": {
    "title": "Google SERP Intelligence Scraper",
    "description": "Track Google and AI search visibility with structured SERP pages, AI answers, citations, ads, brand share of voice, and report-ready outputs for apps, MCP agents, and internal monitoring.",
    "version": "0.2",
    "x-build-id": "dMO4IU3SMMDlmpJyN"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/netdesignr~google-serp-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-netdesignr-google-serp-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/netdesignr~google-serp-scraper/runs": {
      "post": {
        "operationId": "runs-sync-netdesignr-google-serp-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/netdesignr~google-serp-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-netdesignr-google-serp-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 Queries",
            "type": "array",
            "description": "Search queries or full Google Search URLs. One item per line.",
            "items": {
              "type": "string"
            }
          },
          "searchType": {
            "title": "Google Search Type",
            "enum": [
              "web",
              "images",
              "news",
              "shopping"
            ],
            "type": "string",
            "description": "Choose the Google result surface to scrape.",
            "default": "web"
          },
          "forceExactMatch": {
            "title": "Force Exact Match",
            "type": "boolean",
            "description": "Wrap each query in quotes for exact phrase matching.",
            "default": false
          },
          "scrapeMode": {
            "title": "Google Scrape Mode",
            "enum": [
              "auto",
              "light",
              "full"
            ],
            "type": "string",
            "description": "auto selects the best mode. light uses HTTP-only. full uses a browser and is required for richer SERP features and Google AI Mode.",
            "default": "auto"
          },
          "googleAiMode": {
            "title": "Google AI Mode",
            "enum": [
              "off",
              "withSearchResults",
              "only"
            ],
            "type": "string",
            "description": "Capture Google's AI Mode experience. Available for web search only.",
            "default": "off"
          },
          "residentialProxyMode": {
            "title": "Managed Proxy Mode",
            "enum": [
              "off"
            ],
            "type": "string",
            "description": "Managed residential proxy traffic is disabled for profitability. Old saved tasks that still send the deprecated residential value are treated as Off at runtime.",
            "default": "off"
          },
          "includeAiOverview": {
            "title": "Include AI Overview",
            "type": "boolean",
            "description": "Extract Google's AI Overview block from classic web SERPs. Forces full mode.",
            "default": false
          },
          "includeAds": {
            "title": "Include Paid Results",
            "type": "boolean",
            "description": "Extract Google ad blocks and ad metadata.",
            "default": false
          },
          "includePeopleAlsoAsk": {
            "title": "Include People Also Ask",
            "type": "boolean",
            "description": "Extract related questions. Full mode attempts to expand answers.",
            "default": false
          },
          "includeKnowledgePanel": {
            "title": "Include Knowledge Panel",
            "type": "boolean",
            "description": "Extract the right-hand knowledge panel when present. Forces full mode.",
            "default": false
          },
          "includeVideoResults": {
            "title": "Include Video Results",
            "type": "boolean",
            "description": "Extract video blocks when present.",
            "default": false
          },
          "includeLocalPack": {
            "title": "Include Local Pack",
            "type": "boolean",
            "description": "Extract local business results. Forces full mode.",
            "default": false
          },
          "includeIcons": {
            "title": "Include Site Icons",
            "type": "boolean",
            "description": "Extract favicon URLs for organic results when Google exposes them.",
            "default": false
          },
          "enablePerplexity": {
            "title": "Enable Perplexity",
            "type": "boolean",
            "description": "Call Perplexity with your own API key and normalize the answer, citations, and optional extras. Web search only.",
            "default": false
          },
          "perplexityApiKey": {
            "title": "Perplexity API Key",
            "type": "string",
            "description": "Your Perplexity API key. Required only when Enable Perplexity is on. The actor never falls back to a Netdesignr-managed key."
          },
          "perplexityReturnImages": {
            "title": "Perplexity Images",
            "type": "boolean",
            "description": "Request image metadata from Perplexity when available.",
            "default": false
          },
          "perplexityReturnRelatedQuestions": {
            "title": "Perplexity Related Questions",
            "type": "boolean",
            "description": "Request related questions from Perplexity when available.",
            "default": false
          },
          "perplexitySearchRecency": {
            "title": "Perplexity Recency Filter",
            "enum": [
              "",
              "day",
              "week",
              "month",
              "year"
            ],
            "type": "string",
            "description": "Optional recency filter for Perplexity search.",
            "default": ""
          },
          "enableChatGptSearch": {
            "title": "Enable ChatGPT Search",
            "type": "boolean",
            "description": "Call OpenAI's official web search tooling with your own API key and normalize answer visibility. Web search only.",
            "default": false
          },
          "openAiApiKey": {
            "title": "OpenAI API Key",
            "type": "string",
            "description": "Your OpenAI API key. Required only when Enable ChatGPT Search is on. The actor never falls back to a Netdesignr-managed key."
          },
          "chatGptSearchContextSize": {
            "title": "ChatGPT Search Context Size",
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "type": "string",
            "description": "Trade off cost and breadth of web search context for OpenAI web search.",
            "default": "medium"
          },
          "countryCode": {
            "title": "Country",
            "type": "string",
            "description": "Two-letter country code used for Google targeting, for example us, gb, de.",
            "default": "us"
          },
          "searchLanguage": {
            "title": "Search Language (lr)",
            "type": "string",
            "description": "Optional Google language code such as lang_en or lang_de."
          },
          "interfaceLanguage": {
            "title": "Interface Language (hl)",
            "type": "string",
            "description": "Google interface language such as en, de, fr, or ja.",
            "default": "en"
          },
          "locationUule": {
            "title": "UULE Geolocation",
            "type": "string",
            "description": "Optional Google UULE parameter. Use an encoded UULE value or a plain-text location name."
          },
          "maxPagesPerQuery": {
            "title": "Max Pages Per Query",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Number of Google result pages to scrape per query.",
            "default": 1
          },
          "mobileResults": {
            "title": "Mobile Results",
            "type": "boolean",
            "description": "Use a mobile user agent and viewport for Google scraping.",
            "default": false
          },
          "quickDateRange": {
            "title": "Google Date Range",
            "enum": [
              "",
              "d1",
              "w1",
              "m1",
              "y1"
            ],
            "type": "string",
            "description": "Restrict Google results by recency.",
            "default": ""
          },
          "brandDomains": {
            "title": "Brand Domains",
            "type": "array",
            "description": "Domains to track across Google and AI search results.",
            "items": {
              "type": "string"
            }
          },
          "enableBusinessLeadsEnrichment": {
            "title": "Enable Leads Enrichment",
            "type": "boolean",
            "description": "Enrich the top cited domains with homepage and contact signals.",
            "default": false
          },
          "maxLeadDomains": {
            "title": "Max Lead Domains",
            "minimum": 1,
            "maximum": 25,
            "type": "integer",
            "description": "Maximum number of cited domains to enrich.",
            "default": 10
          },
          "saveHtml": {
            "title": "Save Google HTML Snapshots",
            "type": "boolean",
            "description": "Include a trimmed Google HTML snapshot on each raw Google page item.",
            "default": false
          },
          "saveHtmlToKeyValueStore": {
            "title": "Save HTML to Key-Value Store",
            "type": "boolean",
            "description": "Store raw Google page HTML in the run key-value store instead of the dataset.",
            "default": false
          },
          "emitAiResultsToDataset": {
            "title": "Show AI Results in Dataset",
            "type": "boolean",
            "description": "Also write Perplexity, ChatGPT Search, and Google AI Mode records to the default dataset for easier review in Apify. AI records still remain available in AI_ENGINE_RESULTS.json.",
            "default": true
          },
          "outputMode": {
            "title": "Output Mode",
            "enum": [
              "raw",
              "report",
              "both"
            ],
            "type": "string",
            "description": "Emit raw evidence, a normalized visibility report, or both.",
            "default": "raw"
          },
          "emptyRunPolicy": {
            "title": "Empty Run Policy",
            "enum": [
              "retry_then_fail",
              "retry_then_warn",
              "retry_then_succeed"
            ],
            "type": "string",
            "description": "Behavior when the run finishes without emitting any Google or AI records.",
            "default": "retry_then_warn"
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}