openapi: 3.1.0
info:
  title: SearchApi SERP API
  version: v1
  description: >-
    Real-time SERP and search-data API. A single GET endpoint, `/api/v1/search`, returns clean,
    structured JSON results across 100+ search engines selected via the `engine` parameter (Google,
    Google Maps, Google News, Google Scholar, Google Images, Google Shopping, Google Trends, Google
    Jobs, YouTube, Bing, Baidu, DuckDuckGo, Yahoo, Yandex, and marketplace engines such as Amazon,
    Walmart, and eBay). SearchApi handles proxy rotation, CAPTCHA solving, and geo/locale targeting
    server-side. Authenticate with an API key, sent either as an `Authorization: Bearer <key>` header
    or an `api_key` query parameter.

    This description is GENERATED from the public documentation at https://www.searchapi.io/docs —
    SearchApi does not publish a machine-readable OpenAPI/GraphQL contract. Parameters and the response
    envelope are grounded in the documented Google and Google Maps engines; per-engine parameter sets
    and response blocks vary. No fabrication: only documented fields are included, and engine-specific
    fields are noted as such.
  x-provenance:
    generated: '2026-07-24'
    method: generated
    source:
      - https://www.searchapi.io/docs/google
      - https://www.searchapi.io/docs/google-maps
    note: >-
      Faithful reconstruction from public docs. `engine` is intentionally an open string (100+ engines);
      only documented, engine-common parameters are modeled here. Verify per-engine parameters against
      the specific engine's docs page.
  contact:
    name: SearchApi Support
    email: support@searchapi.io
    url: https://www.searchapi.io/docs
  termsOfService: https://www.searchapi.io/legal/terms
servers:
  - url: https://www.searchapi.io
    description: SearchApi production
security:
  - bearerAuth: []
  - apiKeyQuery: []
tags:
  - name: search
    description: Real-time SERP / search-data retrieval across supported engines.
paths:
  /api/v1/search:
    get:
      operationId: search
      summary: Run a search against a chosen engine
      description: >-
        Executes a real-time search on the engine named by `engine` and returns structured JSON. The
        set of accepted parameters and the populated response blocks depend on the selected engine; the
        parameters below are those common to the Google web-search engine (the reference engine). See
        the per-engine docs pages for engine-specific parameters (e.g. `ll` for `google_maps`).
      tags:
        - search
      parameters:
        - name: engine
          in: query
          required: true
          description: >-
            Search engine to query. SearchApi supports 100+ engines. Common values include `google`,
            `google_maps`, `google_news`, `google_scholar`, `google_images`, `google_videos`,
            `google_shopping`, `google_trends`, `google_jobs`, `google_autocomplete`, `google_lens`,
            `google_ai_mode`, `bing`, `duckduckgo`, `yahoo`, `yandex`, `baidu`, `youtube`,
            `amazon_search`, `walmart_search`, `ebay_search`.
          schema:
            type: string
            examples:
              - google
        - name: q
          in: query
          required: true
          description: >-
            Search query. Supports engine search operators (e.g. `site:`, `inurl:`). For some engines
            this parameter carries the engine's primary input (e.g. a place query for `google_maps`).
          schema:
            type: string
            examples:
              - coffee
        - name: api_key
          in: query
          required: false
          description: >-
            API key. Optional here because authentication is normally supplied via the
            `Authorization: Bearer <key>` header; provide it as a query parameter only if you are not
            using the header.
          schema:
            type: string
        - name: location
          in: query
          required: false
          description: Geographic location from which the search is executed. Cannot be combined with `uule`.
          schema:
            type: string
            examples:
              - "Austin, Texas, United States"
        - name: uule
          in: query
          required: false
          description: Google-encoded location string. Cannot be combined with `location`.
          schema:
            type: string
        - name: device
          in: query
          required: false
          description: Device type to emulate.
          schema:
            type: string
            enum: [desktop, mobile, tablet]
            default: desktop
        - name: gl
          in: query
          required: false
          description: Two-letter country code for the results (e.g. `us`, `gb`).
          schema:
            type: string
            default: us
        - name: hl
          in: query
          required: false
          description: Two-letter interface language code (e.g. `en`, `es`).
          schema:
            type: string
            default: en
        - name: lr
          in: query
          required: false
          description: Restrict results to documents in a given language, in `lang_{code}` form (e.g. `lang_en`).
          schema:
            type: string
        - name: cr
          in: query
          required: false
          description: Restrict results to documents originating from a given country.
          schema:
            type: string
        - name: safe
          in: query
          required: false
          description: SafeSearch filtering level.
          schema:
            type: string
            enum: [active, blur, off]
            default: blur
        - name: nfpr
          in: query
          required: false
          description: Set to `1` to exclude results from auto-corrected queries.
          schema:
            type: integer
            enum: [0, 1]
        - name: filter
          in: query
          required: false
          description: Set to `0` to disable the "Similar/Omitted results" duplicate filters.
          schema:
            type: integer
            enum: [0, 1]
        - name: verbatim
          in: query
          required: false
          description: Force exact-keyword (verbatim) matching.
          schema:
            type: boolean
        - name: kgmid
          in: query
          required: false
          description: Knowledge Graph entity id (`/m/` or `/g/` form) to fetch a specific entity.
          schema:
            type: string
        - name: time_period
          in: query
          required: false
          description: Restrict results to a relative time window.
          schema:
            type: string
            enum:
              - last_1_minute
              - last_5_minutes
              - last_15_minutes
              - last_30_minutes
              - last_hour
              - last_day
              - last_week
              - last_month
              - last_year
        - name: time_period_min
          in: query
          required: false
          description: Custom time-window start date, `MM/DD/YYYY`.
          schema:
            type: string
        - name: time_period_max
          in: query
          required: false
          description: Custom time-window end date, `MM/DD/YYYY`.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Results page number.
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: ll
          in: query
          required: false
          description: >-
            GPS coordinates for engines that accept them (notably `google_maps`), in
            `@latitude,longitude,zoom` (e.g. `@40.7455096,-74.0083012,14z`) form.
          schema:
            type: string
        - name: optimization_strategy
          in: query
          required: false
          description: Request optimization approach.
          schema:
            type: string
            enum: [performance, ads]
        - name: zero_retention
          in: query
          required: false
          description: Disable logging/storage of the request and response (Enterprise plans only).
          schema:
            type: boolean
      responses:
        '200':
          description: Structured search results. Populated blocks depend on the engine and query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Bad request — a required parameter is missing or a value is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — account rate/throughput limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Send the API key as: `Authorization: Bearer <api_key>`.'
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Send the API key as the `api_key` query parameter.
  schemas:
    SearchResponse:
      type: object
      description: >-
        Top-level search response envelope. `search_metadata`, `search_parameters`, and
        `search_information` are engine-common; the remaining result blocks (only a representative
        subset is modeled here) appear when the engine and query produce them.
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          type: object
          description: Echo of the request parameters that were applied.
          additionalProperties: true
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
        knowledge_graph:
          type: object
          additionalProperties: true
        answer_box:
          type: object
          additionalProperties: true
        ai_overview:
          type: object
          additionalProperties: true
        related_searches:
          type: array
          items:
            type: object
            additionalProperties: true
        related_questions:
          type: array
          items:
            type: object
            additionalProperties: true
        pagination:
          $ref: '#/components/schemas/Pagination'
      additionalProperties: true
    SearchMetadata:
      type: object
      properties:
        id:
          type: string
          description: Unique search identifier.
        status:
          type: string
          description: Request status, e.g. "Success".
        created_at:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp.
        request_time_taken:
          type: number
          description: Seconds spent on the upstream HTTP request.
        parsing_time_taken:
          type: number
          description: Seconds spent parsing the response.
        total_time_taken:
          type: number
          description: Total processing time in seconds.
        request_url:
          type: string
          description: The upstream search URL that was constructed.
        html_url:
          type: string
          description: SearchApi-hosted HTML results page.
        json_url:
          type: string
          description: SearchApi-hosted JSON results page.
      additionalProperties: true
    SearchInformation:
      type: object
      description: Query-level statistics (fields vary by engine).
      additionalProperties: true
    OrganicResult:
      type: object
      properties:
        position:
          type: integer
          description: Result rank on the page.
        title:
          type: string
        link:
          type: string
          format: uri
        source:
          type: string
          description: Website name / brand.
        domain:
          type: string
        displayed_link:
          type: string
        snippet:
          type: string
        snippet_highlighted_words:
          type: array
          items:
            type: string
        date:
          type: string
        thumbnail:
          type: string
          description: Thumbnail image (may be a URL or base64 data).
        favicon:
          type: string
        sitelinks:
          type: object
          description: Sub-page links with titles/URLs.
          additionalProperties: true
      additionalProperties: true
    Pagination:
      type: object
      properties:
        current:
          type: integer
        next:
          type: string
          format: uri
        other_pages:
          type: object
          additionalProperties:
            type: string
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message.
      additionalProperties: true