openapi: 3.0.3
info:
  title: ValueSERP Search Images Shopping API
  description: Real-time Google SERP data API supporting organic search, shopping, news, images, places, and product results via simple GET requests authenticated with an API key. Returns structured JSON with organic results, ads, knowledge graphs, answer boxes, AI overviews, and more. Operated by Traject Data.
  version: '1.0'
  contact:
    name: ValueSERP Support
    url: https://trajectdata.com/serp/value-serp-api/
  termsOfService: https://trajectdata.com/serp/value-serp-api/
  x-api-id: valueserp-search
servers:
- url: https://api.valueserp.com
  description: ValueSERP Production API
security:
- apiKeyQuery: []
tags:
- name: Shopping
  description: Google Shopping product results.
paths:
  /search#shopping:
    get:
      operationId: googleShopping
      summary: Google Shopping Search
      description: Retrieve real-time Google Shopping product results for a given keyword. Set search_type=shopping. Supports price filtering, condition, merchant filtering, and sorting.
      tags:
      - Shopping
      parameters:
      - $ref: '#/components/parameters/api_key'
      - name: search_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - shopping
        description: Must be set to "shopping".
        example: shopping
      - $ref: '#/components/parameters/q'
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/location_auto'
      - $ref: '#/components/parameters/google_domain'
      - $ref: '#/components/parameters/gl'
      - $ref: '#/components/parameters/hl'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/max_page'
      - $ref: '#/components/parameters/uule'
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - relevance
          - price_low_to_high
          - price_high_to_low
          - review_score
        description: Sort order for shopping results.
        example: relevance
      - name: shopping_buy_on_google
        in: query
        required: false
        schema:
          type: boolean
        description: Include only "Buy on Google" products.
      - name: shopping_filter
        in: query
        required: false
        schema:
          type: string
        description: Filter shopping results by attribute (e.g., brand).
        example: brand
      - name: shopping_price_min
        in: query
        required: false
        schema:
          type: number
          format: decimal
        description: Minimum product price filter.
        example: 4.99
      - name: shopping_price_max
        in: query
        required: false
        schema:
          type: number
          format: decimal
        description: Maximum product price filter.
        example: 29.99
      - name: shopping_condition
        in: query
        required: false
        schema:
          type: string
          enum:
          - new
          - used
        description: Filter by product condition.
        example: new
      - name: shopping_merchants
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated list of merchant IDs to filter results.
      responses:
        '200':
          description: Successful shopping search response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShoppingResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    hl:
      name: hl
      in: query
      required: false
      schema:
        type: string
        default: en
      description: Determines the Google UI language to return results in. BCP-47 language code.
      example: en
    uule:
      name: uule
      in: query
      required: false
      schema:
        type: string
      description: Custom Google UULE parameter to override the location.
    location_auto:
      name: location_auto
      in: query
      required: false
      schema:
        type: boolean
        default: true
      description: When true, automatically updates gl and hl parameters based on the built-in location value. Defaults to true.
    google_domain:
      name: google_domain
      in: query
      required: false
      schema:
        type: string
        default: google.com
      description: The Google domain to use for the search.
      example: google.com
    location:
      name: location
      in: query
      required: false
      schema:
        type: string
      description: Geographic location for the search. Accepts location names (e.g., "manhattan,new york,united states") or GPS coordinates (e.g., "lat 43.437677,lon 3.8392765").
      example: united states
    page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1
      description: The results page number to retrieve. Defaults to 1.
      example: 1
    gl:
      name: gl
      in: query
      required: false
      schema:
        type: string
        default: us
      description: Determines the Google country to use for the query. ISO 3166-1 alpha-2 country code.
      example: us
    api_key:
      name: api_key
      in: query
      required: true
      schema:
        type: string
      description: Your ValueSERP API key. Use "demo" for testing limited queries.
      example: demo
    q:
      name: q
      in: query
      required: true
      schema:
        type: string
      description: The keyword or search query to use.
      example: pizza
    max_page:
      name: max_page
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
      description: Retrieve multiple result pages in a single API request. Specifies the maximum page number to retrieve.
      example: 3
  schemas:
    ErrorResponse:
      type: object
      description: Error response body.
      properties:
        request_info:
          type: object
          properties:
            success:
              type: boolean
              example: false
            message:
              type: string
              description: Human-readable error message.
    ShoppingResult:
      type: object
      description: A single Google Shopping product result.
      properties:
        position:
          type: integer
          description: Position in results.
        title:
          type: string
          description: Product name/title.
        link:
          type: string
          format: uri
          description: Product page URL.
        price:
          type: string
          description: Product price with currency symbol.
        extracted_price:
          type: number
          format: decimal
          description: Numeric price value.
        merchant:
          type: string
          description: Merchant/seller name.
        rating:
          type: number
          format: float
          description: Product rating.
        reviews:
          type: integer
          description: Number of reviews.
        shipping:
          type: string
          description: Shipping information.
        condition:
          type: string
          description: Product condition (new/used).
        thumbnail:
          type: string
          format: uri
          description: Product thumbnail image URL.
    RequestInfo:
      type: object
      description: Meta-information about the API request status.
      properties:
        success:
          type: boolean
          description: Whether the request was processed successfully.
        message:
          type: string
          description: Status message (present on errors or incidents).
        credits_used:
          type: integer
          description: Number of credits consumed by this request.
        credits_remaining:
          type: integer
          description: Number of credits remaining in the account.
    SearchParameters:
      type: object
      description: Echo of the parameters used for the search.
      properties:
        q:
          type: string
          description: The search query keyword used.
        search_type:
          type: string
          description: The type of search performed.
        gl:
          type: string
          description: Country code used.
        hl:
          type: string
          description: Language code used.
        google_domain:
          type: string
          description: Google domain used.
    SearchMetadata:
      type: object
      description: Metadata about the search execution.
      properties:
        id:
          type: string
          description: Unique identifier for this search request.
        google_url:
          type: string
          format: uri
          description: The Google URL that was scraped to generate results.
        total_time_taken:
          type: number
          format: float
          description: Total time taken to process the request in seconds.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the search was created.
    ShoppingResponse:
      type: object
      description: Google Shopping search results response.
      properties:
        request_info:
          $ref: '#/components/schemas/RequestInfo'
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        shopping_results:
          type: array
          items:
            $ref: '#/components/schemas/ShoppingResult'
          description: Shopping product listings.
        filters:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              options:
                type: array
                items:
                  type: object
                  properties:
                    text:
                      type: string
                    link:
                      type: string
                      format: uri
          description: Available shopping filters.
  responses:
    InternalServerError:
      description: Internal Server Error - Retry after a delay; contact support if the issue persists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: Payment Required - Your ValueSERP account has run out of available credits or there is a payment issue.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - The api_key supplied is not valid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad Request - Invalid parameters or unsupported parameter combinations.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: Service Unavailable - Returned during parsing incidents. Requests are not charged. Use skip_on_incident=true to opt out automatically.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Too Many Requests - Your plan's rate limit has been exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: API key for authentication. Pass as the api_key query parameter. Use "demo" as the key for testing.