{
  "openapi": "3.0.1",
  "info": {
    "title": "Google SERP Scraper API, Keyword Rank Checker, Position Tracker",
    "description": "Real destination URLs on 40 of 40 captured Google pages, where a plain fetch read 0 of 29. Google search results API: organic positions, AI Overview sources, related searches, optional People also ask, and a SERP rank tracker showing what moved between runs. Country and language are inputs.",
    "version": "0.1",
    "x-build-id": "1J77bvWNQIXtEMiC3"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/snow_leo_data~google-serp-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-snow_leo_data-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/snow_leo_data~google-serp-scraper/runs": {
      "post": {
        "operationId": "runs-sync-snow_leo_data-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/snow_leo_data~google-serp-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-snow_leo_data-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": "Keywords exactly as you would type them into Google. One run takes as many as you like; Google operators such as site:, intitle: and \"quoted phrase\" work.",
            "default": [
              "apify web scraping"
            ],
            "items": {
              "type": "string"
            }
          },
          "countryCode": {
            "title": "🌍 Country",
            "type": "string",
            "description": "Two-letter country code Google should search from (the gl parameter): us, gb, de, fr, in, au, br, ca. It changes which results rank, not only the language.",
            "default": "us"
          },
          "languageCode": {
            "title": "🗣 Interface language",
            "type": "string",
            "description": "Two-letter language code (the hl parameter): en, de, fr, es, pt, ru, ja. Affects snippets, related queries and date wording.",
            "default": "en"
          },
          "maxPagesPerQuery": {
            "title": "📄 Pages per query",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How deep to page. One page is roughly 10 organic results — measured 6 to 10 across 40 live pages. Google ignores the num parameter today, so depth is the only way to get more. Measured ceiling: results run out between start=100 and start=200, after which Google answers \"did not match any documents\".",
            "default": 1
          },
          "device": {
            "title": "📱 Device",
            "enum": [
              "desktop",
              "mobile"
            ],
            "type": "string",
            "description": "Desktop or mobile ranking. Mobile results differ, which matters when you track positions for a mobile-first site.",
            "default": "desktop"
          },
          "safeSearch": {
            "title": "🛡 Safe search",
            "type": "boolean",
            "description": "Ask Google to filter explicit results (the safe=active parameter).",
            "default": false
          },
          "dateRange": {
            "title": "🕒 Date range",
            "enum": [
              "any",
              "past_hour",
              "past_24_hours",
              "past_week",
              "past_month",
              "past_year"
            ],
            "type": "string",
            "description": "Restrict results by publication date (Google's own tbs=qdr filter).",
            "default": "any"
          },
          "includeOrganic": {
            "title": "🔗 Organic results",
            "type": "boolean",
            "description": "Position, title, real destination URL, displayed link, description, domain and publication date.",
            "default": true
          },
          "includeRelatedQueries": {
            "title": "🔁 Related queries",
            "type": "boolean",
            "description": "The \"People also search for\" block: 8 to 11 keyword ideas per page, each with its own Google search URL.",
            "default": true
          },
          "includeAiOverview": {
            "title": "🤖 AI Overview sources",
            "type": "boolean",
            "description": "The pages Google's AI Overview cites, plus the overview text itself. Measured: present on 25 of 40 live pages, 2 to 12 sources each.",
            "default": true
          },
          "includePeopleAlsoAsk": {
            "title": "❓ People also ask",
            "type": "boolean",
            "description": "Questions from the \"People also ask\" box. Off by default because it costs one extra page load per query: measured on 40 lightweight pages, the block was on none of them, and it only appears on Google's JavaScript version.",
            "default": false
          },
          "trackPositions": {
            "title": "📈 Track positions between runs",
            "type": "boolean",
            "description": "Remember where each URL ranked for each query and return only what moved. Every row gets change_type (NEW / UP / DOWN / UNCHANGED / GONE), previous_position and position_change. URLs that dropped out of the results come back as GONE rows.",
            "default": false
          },
          "emitUnchanged": {
            "title": "➖ Also return unchanged positions",
            "type": "boolean",
            "description": "With position tracking on, return rows that did not move as well. Off means you are not charged twice for the same position.",
            "default": false
          },
          "domainContains": {
            "title": "✅ Keep only these domains",
            "type": "array",
            "description": "Keep organic rows whose domain contains any of these strings. Empty means keep all. Filters apply to organic rows only, and a row is never dropped for a field Google left empty.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "excludeDomains": {
            "title": "🚫 Drop these domains",
            "type": "array",
            "description": "Drop organic rows whose domain contains any of these strings — useful to remove your own site, or aggregators.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "titleContains": {
            "title": "🔤 Title must contain",
            "type": "array",
            "description": "Keep organic rows whose title contains any of these strings.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxItems": {
            "title": "🔢 Maximum rows",
            "minimum": 0,
            "type": "integer",
            "description": "Hard cap on rows written to the dataset. It limits the OUTPUT, not the crawl: pages are still walked so filters have something to work on.",
            "default": 0
          },
          "maxAttempts": {
            "title": "🔁 Attempts per page",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Google serves two different pages for the same query, and only one of them carries real destination URLs; which one you get is decided by the proxy session. Measured 17.09.2026: 40 of 40 pages came back readable, 3 of them with Google's encrypted link markers, which a fresh session fixes. Attempts are not charged to you — you pay per delivered page.",
            "default": 3
          },
          "requireResolvedLinks": {
            "title": "🔒 Only rows with a real URL",
            "type": "boolean",
            "description": "Drop organic rows when Google returned its encrypted /goto marker instead of an address, rather than handing you a row with an empty url. Title, displayed link and domain would still be there without it.",
            "default": true
          },
          "serpProxyFallback": {
            "title": "🛟 Fall back to the Google SERP proxy",
            "type": "boolean",
            "description": "If Google challenges the datacenter address, retry through Apify's Google SERP proxy. Measured: 24 of 24 datacenter requests went through without a challenge, so this is a safety net, not the normal path.",
            "default": true
          },
          "compactOutput": {
            "title": "🧱 Compact output",
            "type": "boolean",
            "description": "Nine columns instead of twenty-two: position, type, title, url, domain, query, page, change_type, position_change. Built for AI agents and for rank-tracking spreadsheets.",
            "default": false
          },
          "excludeEmptyFields": {
            "title": "🧹 Drop empty fields",
            "type": "boolean",
            "description": "Leave empty columns out of each row entirely, instead of returning them as null.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "🌐 Proxy",
            "type": "object",
            "description": "Apify Proxy is required: Google answers a consent page to a direct request from the cloud. The default is the shared datacenter pool, which measured 24 successful pages out of 24. The Google SERP group is used automatically as a fallback when a datacenter address is challenged.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}