{
  "openapi": "3.0.3",
  "info": {
    "title": "SerpApi.Org REST API",
    "version": "1.0.0",
    "description": "Real-time Search Engine Results Page (SERP) and web data extraction API — web, image, video, news, and shopping search, plus autocomplete, scholar, maps, reviews, Google Trends, webpage extraction, IP geolocation, currency/crypto rates, and domain intelligence. All endpoints return JSON and are authenticated with a `token` query parameter.",
    "contact": { "name": "SerpApi.Org Support", "url": "https://serpapi.org/contact" }
  },
  "servers": [
    { "url": "https://serpapi.org/api/v1", "description": "Production" }
  ],
  "security": [{ "ApiKeyAuth": [] }],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "Your SerpApi.Org secret API key. Get one free at https://serpapi.org/pricing"
      }
    },
    "parameters": {
      "keyword": { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query / keyword. `q` is accepted as an alias." },
      "page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Result page number." },
      "size": { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "default": 40, "maximum": 100 }, "description": "Number of results to return (max 100)." },
      "time": { "name": "time", "in": "query", "required": false, "schema": { "type": "string", "enum": ["h", "d", "w", "m", "y"] }, "description": "Freshness filter: hour, day, week, month, or year." },
      "gl": { "name": "gl", "in": "query", "required": false, "schema": { "type": "string", "default": "US" }, "description": "Two-letter country code to localize results (e.g. `us`, `gb`, `vn`)." },
      "hl": { "name": "hl", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Two-letter language code (auto-detected from `gl` if omitted)." }
    },
    "schemas": {
      "SearchEnvelope": {
        "type": "object",
        "properties": {
          "status": { "type": "boolean", "example": true },
          "request": { "type": "object", "description": "Echo of the normalized request parameters." },
          "data": { "type": "object", "description": "Endpoint-specific payload — see the `data` shape column in the response example." },
          "in_seconds": { "type": "number", "format": "float", "example": 0.42 }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "status": { "type": "boolean", "example": false },
          "message": { "type": "string", "example": "Invalid or missing API token." }
        }
      }
    },
    "responses": {
      "Success": {
        "description": "Successful response",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchEnvelope" } } }
      },
      "Error": {
        "description": "Request failed (invalid token, missing parameter, or upstream error)",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      }
    }
  },
  "paths": {
    "/webs-search": {
      "get": {
        "summary": "Web Search API",
        "description": "Live organic web search results (title, link, description, position) for a keyword.",
        "tags": ["Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/size" },
          { "$ref": "#/components/parameters/time" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/images-search": {
      "get": {
        "summary": "Image Search API",
        "description": "Image search results with thumbnail, source, and full-size image URLs.",
        "tags": ["Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/size" },
          { "$ref": "#/components/parameters/time" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/videos-search": {
      "get": {
        "summary": "Video Search API",
        "description": "Video results with thumbnail, duration, source, and link metadata.",
        "tags": ["Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/size" },
          { "$ref": "#/components/parameters/time" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/news-search": {
      "get": {
        "summary": "News Search API",
        "description": "Live news headlines with source, publish date, thumbnail, and link.",
        "tags": ["Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/size" },
          { "$ref": "#/components/parameters/time" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/shopping-search": {
      "get": {
        "summary": "Shopping Search API",
        "description": "Product listings with price, merchant, rating, and image.",
        "tags": ["Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/size" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/autocomplete": {
      "get": {
        "summary": "Autocomplete API",
        "description": "Search-engine autocomplete/suggestion strings for a seed keyword.",
        "tags": ["Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "name": "cc", "in": "query", "required": false, "schema": { "type": "string", "default": "US" }, "description": "Two-letter country code, maps internally to a market code." },
          { "name": "mkt", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Explicit market code (overridden if `cc` is supplied)." }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/scholar-search": {
      "get": {
        "summary": "Scholar Search API",
        "description": "Academic paper results with citation counts, authors, and abstract snippets.",
        "tags": ["Expanded Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/maps-search": {
      "get": {
        "summary": "Maps Search API",
        "description": "Local business results with address, rating, and coordinates.",
        "tags": ["Expanded Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/reviews-search": {
      "get": {
        "summary": "Reviews API",
        "description": "Customer review results for a business or product query.",
        "tags": ["Expanded Search"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/webpage": {
      "get": {
        "summary": "Webpage Extraction API",
        "description": "Fetches a URL and returns extracted text/HTML content.",
        "tags": ["Utility"],
        "parameters": [
          { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "description": "Fully-qualified URL to fetch and extract." }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/trends-now-search": {
      "get": {
        "summary": "Google Trends — Trending Now",
        "description": "Currently trending search topics. Does not require a keyword.",
        "tags": ["Trends"],
        "parameters": [
          { "$ref": "#/components/parameters/gl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/trends-interest-search": {
      "get": {
        "summary": "Google Trends — Interest Over Time",
        "description": "Search interest over time for a given keyword.",
        "tags": ["Trends"],
        "parameters": [
          { "$ref": "#/components/parameters/keyword" },
          { "$ref": "#/components/parameters/gl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/ip-lookup": {
      "get": {
        "summary": "IP Lookup API",
        "description": "IP geolocation, ISP/ASN, timezone, and VPN/proxy/hosting detection flags. Omit `ip` to resolve the caller's own IP.",
        "tags": ["Utility"],
        "parameters": [
          { "name": "ip", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IPv4 or IPv6 address. If omitted, the caller's IP is auto-detected." }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/exchange-rate": {
      "get": {
        "summary": "Exchange Rate API",
        "description": "Live fiat currency exchange rates. Omit `to` to return all available currencies for the base.",
        "tags": ["Utility"],
        "parameters": [
          { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "default": "USD" }, "description": "Base currency ISO code." },
          { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Target currency ISO code. Omit for all rates." }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/crypto-price": {
      "get": {
        "summary": "Crypto Price API",
        "description": "Real-time cryptocurrency prices. Omit `symbols` for top-10 defaults.",
        "tags": ["Utility"],
        "parameters": [
          { "name": "symbols", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated crypto symbols, e.g. `btc,eth,sol`." },
          { "name": "vs_currencies", "in": "query", "required": false, "schema": { "type": "string", "default": "usd" }, "description": "Comma-separated fiat currencies to price against, e.g. `usd,eur`." }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/domain-info": {
      "get": {
        "summary": "Domain Intelligence API",
        "description": "WHOIS, SSL certificate, DNS records, subdomains, and URL preview for a domain.",
        "tags": ["Utility"],
        "parameters": [
          { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Root domain to inspect, e.g. `example.com`." }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    },
    "/search": {
      "get": {
        "summary": "Unified Search API",
        "description": "Single endpoint that dispatches to any of the search/utility engines above based on the `type` parameter. Convenient for SDKs and integrations that want one call signature for every data source.",
        "tags": ["Search"],
        "parameters": [
          { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": ["web", "images", "videos", "news", "autocomplete", "shopping", "scholar", "maps", "reviews", "webpage", "trends-now", "trends-interest", "ip-lookup", "exchange-rate", "crypto-price", "domain-info"], "default": "web" }, "description": "Which data source to query." },
          { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Required for all types except `webpage`, `trends-now`, and the utility types (`ip-lookup`, `exchange-rate`, `crypto-price`, `domain-info`). `q` is accepted as an alias." },
          { "name": "url", "in": "query", "required": false, "schema": { "type": "string", "format": "uri" }, "description": "Required when `type=webpage`." },
          { "$ref": "#/components/parameters/page" },
          { "$ref": "#/components/parameters/size" },
          { "$ref": "#/components/parameters/gl" },
          { "$ref": "#/components/parameters/hl" }
        ],
        "responses": { "200": { "$ref": "#/components/responses/Success" }, "422": { "$ref": "#/components/responses/Error" } }
      }
    }
  }
}