openapi: 3.0.3
info:
  title: Zenserp Search Batch API
  description: REST API for scraping real-time Google search results including organic results, paid ads, featured snippets, knowledge graphs, related questions, maps, news, shopping, images, videos, YouTube, Bing, Yandex, and DuckDuckGo search results. Supports geolocation targeting across 200+ countries and languages.
  version: '2.0'
  contact:
    name: Zenserp Support
    url: https://zenserp.com/
    email: support@zenserp.com
  termsOfService: https://zenserp.com/terms-of-service/
  x-logo:
    url: https://zenserp.com/wp-content/uploads/2019/07/zenserp-logo.png
servers:
- url: https://app.zenserp.com/api/v2
  description: Zenserp API v2
security:
- apiKeyHeader: []
- apiKeyQuery: []
tags:
- name: Batch
  description: Batch processing for multiple simultaneous queries.
paths:
  /batch:
    post:
      operationId: batchSearch
      summary: Batch Search
      description: Submit multiple search queries in a single API request. Available on Medium plan and above. Each item in the batch uses the same parameters as the `/search` endpoint.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
            example:
              queries:
              - q: pied piper
                gl: us
                hl: en
              - q: silicon valley tv show
                gl: us
                hl: en
      responses:
        '200':
          description: Batch search results array.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: Plan does not support batch requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    KnowledgeGraph:
      type: object
      description: Google Knowledge Graph panel data.
      properties:
        title:
          type: string
        type:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        image:
          type: string
          format: uri
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Key-value entity attributes from the knowledge panel.
    ShoppingResult:
      type: object
      description: A single Google Shopping product result.
      properties:
        position:
          type: integer
        title:
          type: string
        url:
          type: string
          format: uri
        price:
          type: string
          description: Product price as a formatted string (e.g., "$29.99").
        store:
          type: string
          description: Merchant/store name.
        rating:
          type: number
          format: float
          description: Product rating (0-5).
        reviews:
          type: integer
          description: Number of reviews.
        thumbnail:
          type: string
          format: uri
    RelatedQuestion:
      type: object
      description: A People Also Ask question-answer pair.
      properties:
        question:
          type: string
        answer:
          type: string
        url:
          type: string
          format: uri
        title:
          type: string
    OrganicResult:
      type: object
      description: A single organic (non-paid) search result.
      properties:
        position:
          type: integer
          description: 1-based ranking position in results.
        title:
          type: string
          description: Title of the result.
        url:
          type: string
          format: uri
          description: URL of the result page.
        domain:
          type: string
          description: Domain of the result.
        description:
          type: string
          description: Snippet/description text for the result.
        favicon:
          type: string
          format: uri
          description: URL of the site favicon.
        sitelinks:
          type: array
          description: Additional sub-links shown below the main result.
          items:
            type: object
            properties:
              title:
                type: string
              url:
                type: string
                format: uri
    SearchResponse:
      type: object
      description: Top-level search result object returned by the /search endpoint.
      properties:
        request_info:
          $ref: '#/components/schemas/RequestInfo'
        query:
          $ref: '#/components/schemas/QueryInfo'
        organic_results:
          type: array
          description: List of organic (non-paid) search results.
          items:
            $ref: '#/components/schemas/OrganicResult'
        paid_results:
          type: array
          description: List of paid advertisement results.
          items:
            $ref: '#/components/schemas/PaidResult'
        featured_snippet:
          $ref: '#/components/schemas/FeaturedSnippet'
        knowledge_graph:
          $ref: '#/components/schemas/KnowledgeGraph'
        related_questions:
          type: array
          description: People Also Ask questions and answers.
          items:
            $ref: '#/components/schemas/RelatedQuestion'
        related_searches:
          type: array
          description: Related search suggestions.
          items:
            $ref: '#/components/schemas/RelatedSearch'
        image_results:
          type: array
          description: Image results (when tbm=isch).
          items:
            $ref: '#/components/schemas/ImageResult'
        news_results:
          type: array
          description: News article results (when tbm=nws).
          items:
            $ref: '#/components/schemas/NewsResult'
        shopping_results:
          type: array
          description: Shopping product results (when tbm=shop).
          items:
            $ref: '#/components/schemas/ShoppingResult'
        map_results:
          type: array
          description: Local business results (when tbm=map).
          items:
            $ref: '#/components/schemas/MapResult'
        video_results:
          type: array
          description: Video/YouTube results (when tbm=vid).
          items:
            $ref: '#/components/schemas/VideoResult'
        trends_results:
          type: array
          description: Google Trends data points (when tbm=trends).
          items:
            $ref: '#/components/schemas/TrendsResult'
    RelatedSearch:
      type: object
      description: A related search suggestion.
      properties:
        query:
          type: string
          description: Related query text.
    ErrorResponse:
      type: object
      description: API error response.
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: integer
          description: HTTP status code.
    NewsResult:
      type: object
      description: A single news article result.
      properties:
        position:
          type: integer
        title:
          type: string
        url:
          type: string
          format: uri
        source:
          type: string
          description: News source name.
        published_at:
          type: string
          description: Publication timestamp or relative time.
        thumbnail:
          type: string
          format: uri
    RequestInfo:
      type: object
      description: Metadata about the API request.
      properties:
        success:
          type: boolean
          description: Whether the request was successful.
        credits_used:
          type: integer
          description: Number of API credits consumed by this request.
        credits_remaining:
          type: integer
          description: Remaining credits in the current billing period.
    VideoResult:
      type: object
      description: A single YouTube/video search result.
      properties:
        position:
          type: integer
        title:
          type: string
        url:
          type: string
          format: uri
        channel:
          type: string
          description: Channel or uploader name.
        published_at:
          type: string
          description: Video publication date or relative time.
        duration:
          type: string
          description: Video duration (e.g., "5:32").
        views:
          type: string
          description: View count as formatted string.
        thumbnail:
          type: string
          format: uri
    ImageResult:
      type: object
      description: A single image search result.
      properties:
        position:
          type: integer
        title:
          type: string
        url:
          type: string
          format: uri
        image_url:
          type: string
          format: uri
          description: Direct URL to the image.
        thumbnail:
          type: string
          format: uri
          description: URL to thumbnail version.
        source:
          type: string
          description: Originating website domain.
    BatchRequest:
      type: object
      description: Batch search request body.
      required:
      - queries
      properties:
        queries:
          type: array
          description: Array of search query objects (same parameters as /search).
          minItems: 1
          maxItems: 100
          items:
            type: object
            required:
            - q
            properties:
              q:
                type: string
              gl:
                type: string
              hl:
                type: string
              num:
                type: integer
                minimum: 1
                maximum: 100
              engine:
                type: string
                enum:
                - google
                - bing
                - yandex
                - duckduckgo
              tbm:
                type: string
              location:
                type: string
              device:
                type: string
    QueryInfo:
      type: object
      description: Echo of the query parameters used for this search.
      properties:
        q:
          type: string
          description: The search query.
        gl:
          type: string
          description: Country code used.
        hl:
          type: string
          description: Language code used.
        num:
          type: integer
          description: Number of results requested.
        engine:
          type: string
          description: Search engine used.
        tbm:
          type: string
          description: Search type modifier used.
        location:
          type: string
          description: Geo location used.
    BatchResponse:
      type: object
      description: Batch search response.
      properties:
        request_info:
          $ref: '#/components/schemas/RequestInfo'
        results:
          type: array
          description: Array of search result objects, one per query.
          items:
            $ref: '#/components/schemas/SearchResponse'
    TrendsResult:
      type: object
      description: A Google Trends comparison data point.
      properties:
        query:
          type: string
          description: The search term being tracked.
        date:
          type: string
          description: Date or time period.
        value:
          type: integer
          description: Relative popularity score (0-100).
    MapResult:
      type: object
      description: A single Google Maps local business result.
      properties:
        position:
          type: integer
        title:
          type: string
        address:
          type: string
        phone:
          type: string
        website:
          type: string
          format: uri
        rating:
          type: number
          format: float
        reviews:
          type: integer
        category:
          type: string
        hours:
          type: string
          description: Business hours summary.
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
    FeaturedSnippet:
      type: object
      description: Google featured snippet (answer box).
      properties:
        title:
          type: string
        url:
          type: string
          format: uri
        description:
          type: string
        type:
          type: string
          description: Snippet type (paragraph, table, list, etc.).
    PaidResult:
      type: object
      description: A paid advertisement result.
      properties:
        position:
          type: integer
          description: Ad position.
        title:
          type: string
        url:
          type: string
          format: uri
        domain:
          type: string
        description:
          type: string
        displayed_url:
          type: string
          description: The URL as displayed in the ad.
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: apikey
      description: API key passed in the request header.
    apiKeyQuery:
      type: apiKey
      in: query
      name: apikey
      description: API key passed as a query parameter.