SearchApi SERP API

openapi: 3.2.0
info:
  title: SearchApi SERP Search 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
          - false
          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:
  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
    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
    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
    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
  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.