> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Shopping price history

> Return source-reported dated price observations per store for a numeric Google catalog product_id and selected country. Uses the default product offer. Composite offer identifiers and page tokens are not supported. Dates have day precision; no interpolation, currency conversion or merging of same-named store series. Products/markets without a chart return 404 PRICE_HISTORY_UNAVAILABLE without charge. Current-price listings are never substituted for history.

Costs **1 credit** for a successful live history response. Errors, cache hits, and successful idempotent replays cost zero credits.

Supply a **numeric Google catalog product ID** and a country code (default US). This release uses the default product offer. Composite `catalogid:...,productid:...` identifiers and opaque offer/page tokens are not supported; they return an uncharged 422 instead of silently selecting a different variant. Country inputs use the provider's supported codes; GB selects its UK edition.

The response contains `stores[].prices[]`, with source-reported `date` and `price` observations, the source currency, and the product title. Dates are normalized to ISO calendar dates and sorted ascending within each source series. No missing dates are interpolated, no currency conversion is applied, and stores with the same display name are not merged. `source_index` preserves their separate source positions.

These observations describe price changes and are not a complete daily series, a nationwide quote, or a checkout price. History availability varies by product and market. A recognized product without a chart returns **404 `PRICE_HISTORY_UNAVAILABLE`**, uncharged. Malformed dates, mismatched request identity, or incomplete series fail without returning a partial history. Current-price listings are never substituted for history.

Limits are 100 source series, 5,000 observations per series, and 10,000 observations overall; oversized responses fail. Source: [SerpApi Google Product API](https://serpapi.com/google-product-api), using the existing free search allowance. Live fixture evidence covers a US chart and an unavailable UK chart; it does not certify every country or product.


## OpenAPI

````yaml GET /google_shopping/price-history
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /google_shopping/price-history:
    get:
      tags:
        - Google Shopping
      summary: Google Shopping Price History
      description: >-
        Return source-reported dated price observations per store for a numeric
        Google catalog product_id and selected country. Uses the default product
        offer. Composite offer identifiers and page tokens are not supported.
        Dates have day precision; no interpolation, currency conversion or
        merging of same-named store series. Products/markets without a chart
        return 404 PRICE_HISTORY_UNAVAILABLE without charge. Current-price
        listings are never substituted for history.
      operationId: get_google_shopping_price_history
      parameters:
        - name: product_id
          in: query
          required: true
          example: '4337405995804634306'
          schema:
            type: string
            pattern: ^[1-9][0-9]{0,24}$
          description: >-
            Numeric Google catalog identifier. Composite prds/offer identifiers
            and page tokens are not yet supported.
        - name: country
          in: query
          required: false
          schema:
            type: string
          description: >-
            Provider-supported two-letter country code, default US; GB maps to
            the UK edition. Chart availability is product- and market-dependent.
          example: US
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            Return source-reported dated price observations per store for a
            numeric Google catalog product_id and selected country. Uses the
            default product offer. Composite offer identifiers and page tokens
            are not supported. Dates have day precision; no interpolation,
            currency conversion or merging of same-named store series.
            Products/markets without a chart return 404
            PRICE_HISTORY_UNAVAILABLE without charge. Current-price listings are
            never substituted for history.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          product_id:
                            type: string
                          title:
                            type: string
                          country:
                            type: string
                          currency:
                            type: string
                          price_history:
                            type: boolean
                            const: true
                          stores:
                            type: array
                            minItems: 1
                            maxItems: 100
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                source_index:
                                  type: integer
                                  minimum: 0
                                prices:
                                  type: array
                                  minItems: 1
                                  maxItems: 5000
                                  items:
                                    type: object
                                    properties:
                                      date:
                                        type: string
                                        format: date
                                      price:
                                        type: number
                                        minimum: 0
                                    required:
                                      - date
                                      - price
                                    additionalProperties: false
                              required:
                                - name
                                - source_index
                                - prices
                              additionalProperties: false
                          store_count:
                            type: integer
                            minimum: 1
                          observation_count:
                            type: integer
                            minimum: 1
                            maximum: 10000
                          date_precision:
                            type: string
                            const: day
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - product_id
                          - title
                          - country
                          - currency
                          - price_history
                          - stores
                          - store_count
                          - observation_count
                          - date_precision
                          - source
                          - coverage_note
                        additionalProperties: false
                    required:
                      - data
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.