SocialCrawl Google Shopping API

openapi: 3.2.0
info:
  title: SocialCrawl Google Shopping API
  version: 1.0.0
  description: 'Unified social media data API - one API key, one consistent response format, 50 platforms, 400 endpoints. Power AI agents with clean social data.


    Slim variant: inline examples removed and the shared error responses hoisted into components. The full annotated spec is at https://www.socialcrawl.dev/openapi.json.'
  contact:
    name: SocialCrawl
    url: https://www.socialcrawl.dev
    email: support@socialcrawl.dev
servers:
- url: https://www.socialcrawl.dev/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: google_shopping
  description: Google_shopping endpoints
paths:
  /google_shopping/product-search:
    get:
      summary: Search Google Shopping products
      description: Searches Google Shopping for products matching a keyword. Returns a unified ProductList with title, seller, price (current/original/currency), rating, image URLs, and the opaque product identifiers (id, ext.gid, ext.data_docid) required to fetch product detail, reviews, or sellers. Sourced from DataForSEO's task-based Merchant/Google API; the async lifecycle is handled server-side, so this is an ordinary synchronous request. First calls take ~20-30s, then serve from cache.
      tags:
      - google_shopping
      operationId: get_google_shopping_product_search
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      parameters:
      - name: query
        in: query
        required: true
        description: Product search keyword (e.g. 'wireless earbuds').
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: Country as an ISO code ('US', 'GB') or full name ('United States'). Defaults to United States.
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: Language code (e.g. 'en'). Defaults to en.
        schema:
          type: string
      - name: depth
        in: query
        required: false
        description: Number of product results to retrieve (default 40, max 120). More results = longer task time.
        schema:
          type: integer
      - name: price_min
        in: query
        required: false
        description: Minimum product price filter.
        schema:
          type: string
      - name: price_max
        in: query
        required: false
        description: Maximum product price filter.
        schema:
          type: string
      - name: sort_by
        in: query
        required: false
        description: 'Result ordering: review_score, price_low_to_high, or price_high_to_low.'
        schema:
          type: string
          enum:
          - review_score
          - price_low_to_high
          - price_high_to_low
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
              schema:
                type: integer
                minimum: 0
            X-Idempotent-Replay:
              description: Present with value `true` only when this response replays a settled idempotency record.
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the request succeeded
                  platform:
                    type: string
                    description: Platform name
                  endpoint:
                    type: string
                    description: API endpoint path
                  data:
                    type: object
                    description: Platform-specific response data
                    properties:
                      items:
                        type: array
                        description: Array of canonical product wrappers ({ product })
                        items:
                          type: object
                          description: Canonical product wrapper
                          properties:
                            product:
                              type: object
                              description: Canonical Product object (unified across commerce platforms)
                              properties:
                                id:
                                  type: string
                                  description: Platform product ID (Amazon ASIN / Google Shopping product id)
                                url:
                                  type:
                                  - string
                                  - 'null'
                                  description: Direct URL to the product page
                                title:
                                  type:
                                  - string
                                  - 'null'
                                  description: Product title
                                description:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at product.description
                                seller:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at product.seller
                                brand:
                                  type:
                                  - string
                                  - 'null'
                                  description: Brand name (cleaned). Null when the platform exposes a seller instead.
                                price:
                                  type: object
                                  description: Price block (current, original/list, currency)
                                  properties:
                                    current:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.price.current
                                    original:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.price.original
                                    currency:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.price.currency
                                rating:
                                  type: object
                                  description: Aggregate rating (average + number of ratings)
                                  properties:
                                    average:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.rating.average
                                    count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.rating.count
                                image_urls:
                                  type:
                                  - string
                                  - array
                                  - 'null'
                                  description: Primary image URL, or an array of image URLs for products with a gallery.
                                  items:
                                    type: string
                                    description: Primary image URL, or an array of image URLs for products with a gallery.
                                availability:
                                  type:
                                  - string
                                  - 'null'
                                  description: Stock/availability string when surfaced
                                reviews_count:
                                  type:
                                  - integer
                                  - 'null'
                                  description: Numeric at product.reviews_count
                                features:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at product.features
                                  items:
                                    type: string
                                    description: String at product.features
                                specifications:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at product.specifications
                                  items:
                                    type: object
                                    description: 'Nested object: product.specifications'
                                    properties:
                                      group:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.specifications.group
                                      name:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.specifications.name
                                      value:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.specifications.value
                                variations:
                                  type:
                                  - array
                                  - 'null'
                                  description: Array at product.variations
                                  items:
                                    type: object
                                    description: 'Nested object: product.variations'
                                    properties:
                                      id:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.id
                                      title:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.title
                                      url:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.url
                                      category:
                                        type:
                                        - string
                                        - 'null'
                                        description: String at product.variations.category
                                ext:
                                  type:
                                  - object
                                  - 'null'
                                  description: 'Nested object: product.ext'
                                  properties:
                                    gid:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.gid
                                    data_docid:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.data_docid
                                    pvf:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.pvf
                                    seller_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.seller_id
                                    sold_count:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.ext.sold_count
                                    catalog_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.catalog_id
                                    requested_id:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.requested_id
                                    rating_distribution:
                                      type:
                                      - object
                                      - 'null'
                                      description: 'Nested object: product.ext.rating_distribution'
                                      properties:
                                        star_1:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_1
                                        star_2:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_2
                                        star_3:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_3
                                        star_4:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_4
                                        star_5:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.rating_distribution.star_5
                                    store_inventory:
                                      type:
                                      - array
                                      - 'null'
                                      description: Array at product.ext.store_inventory
                                      items:
                                        type: object
                                        description: 'Nested object: product.ext.store_inventory'
                                        properties:
                                          store_id:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at product.ext.store_inventory.store_id
                                          store_name:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at product.ext.store_inventory.store_name
                                          state:
                                            type:
                                            - string
                                            - 'null'
                                            description: String at product.ext.store_inventory.state
                                          in_stock:
                                            type:
                                            - boolean
                                            - 'null'
                                            description: Boolean at product.ext.store_inventory.in_stock
                                          quantity:
                                            type:
                                            - integer
                                            - 'null'
                                            description: Numeric at product.ext.store_inventory.quantity
                                    condition:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.condition
                                    available_quantity:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.ext.available_quantity
                                    watchers:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at product.ext.watchers
                                    sold_at:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.sold_at
                                    sold_caption:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.sold_caption
                                    buying_format:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at product.ext.buying_format
                                    seller_reputation:
                                      type:
                                      - object
                                      - 'null'
                                      description: 'Nested object: product.ext.seller_reputation'
                                      properties:
                                        feedback_percentage:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.seller_reputation.feedback_percentage
                                        feedback_count:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.seller_reputation.feedback_count
                                        top_rated:
                                          type:
                                          - boolean
                                          - 'null'
                                          description: Boolean at product.ext.seller_reputation.top_rated
                                        items_sold:
                                          type:
                                          - integer
                                          - 'null'
                                          description: Numeric at product.ext.seller_reputation.items_sold
                                        joined:
                                          type:
                                          - string
                                          - 'null'
                                          description: String at product.ext.seller_reputation.joined
                                        url:
                                          type:
                                          - string
                                          - 'null'
                                          description: String at product.ext.seller_reputation.url
                                        detailed_ratings:
                                          type:
                                          - object
                                          - 'null'
                                          description: 'Nested object: product.ext.seller_reputation.detailed_ratings'
                                          properties:
                                            accurate_description:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.accurate_description
                                            reasonable_shipping_cost:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.reasonable_shipping_cost
                                            shipping_speed:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.shipping_speed
                                            communication:
                                              type:
                                              - integer
                                              - 'null'
                                              description: Numeric at product.ext.seller_reputation.detailed_ratings.communication
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results.
                      total:
                        type:
                        - integer
                        - 'null'
                        description: Total number of matching results, when the upstream provides a count. Omitted otherwise.
                      dropped:
                        type: integer
                        description: Number of upstream list items dropped because they could not be repaired to the endpoint schema. Valid list responses include 0.
                      _warnings:
                        type: array
                        description: 'Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as ''no warnings''.'
                        items:
                          type: string
                          description: One advisory notice.
                    required:
                    - dropped
                  credits_used:
                    type: integer
                    description: Number of credits consumed
                  credits_remaining:
                    type:
                    - integer
                    - 'null'
                    description: Current account balance. Null only when an idempotency replay succeeds but its transient balance lookup fails.
                  request_id:
                    type: string
                    description: Unique request identifier for support
                  cached:
                    type: boolean
                    description: Whether the response was served from cache
                  idempotent_replay:
                    type: boolean
                    description: True only when this response is an idempotency replay
                  pagination:
                    type: object
                    description: Cursor state for this page. Present on every list response.
                    properties:
                      next_cursor:
                        type:
                        - string
                        - 'null'
                        description: Opaque token to send back as `cursor` for the next page, or null at end-of-list. Pass it back verbatim; never decode or trim it.
                      has_more:
                        type: boolean
                        description: Explicit stop signal. Prefer this over inspecting next_cursor or comparing against total.
                      page_size:
                        type: integer
                        description: Number of items in THIS page.
                    required:
                    - next_cursor
                    - has_more
                    - page_size
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
                - pagination
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '413':
          $ref: '#/components/responses/Error413'
        '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'
  /google_shopping/product:
    get:
      summary: Get Google Shopping product detail
      description: 'Returns the full detail for a single Google Shopping product: title, description, rating, image gallery, feature bullets, specifications (grouped name/value), and product variations. Pass any one of the opaque identifiers (product_id, gid, or data_docid) returned by /v1/google_shopping/product-search: all three are recommended for accuracy.'
      tags:
      - google_shopping
      operationId: get_google_shopping_product
      security:
      - ApiKeyAuth: []
      x-credit-tier: standard
      x-credit-cost: 1
      x-socialcrawl-oneOf:
      - - product_id
        - gid
        - data_docid
      parameters:
      - name: product_id
        in: query
        required: false
        description: 'Google Shopping product_id (from product-search). (one of: product_id, gid, data_docid; at least one required)'
        schema:
          type: string
      - name: gid
        in: query
        required: false
        description: 'Google Shopping gid (from product-search). (one of: product_id, gid, data_docid; at least one required)'
        schema:
          type: string
      - name: data_docid
        in: query
        required: false
        description: 'Google Shopping data_docid (from product-search). (one of: product_id, gid, data_docid; at least one required)'
        schema:
          type: string
      - name: country
        in: query
        required: false
        description: Country as an ISO code ('US', 'GB') or full name ('United States'). Defaults to United States.
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: Language code. Defaults to en.
        schema:
          type: string
      - name: Cache-Control
        in: header
        required: false
        description: Send `no-cache` to bypass the response cache and force a live fetch. Billed at the normal endpoint cost; the fresh result is written back to cache for the next caller. Only the `no-cache` directive triggers this. See the Response Schema guide for details.
        schema:
          type: string
      - name: Idempotency-Key
        in: header
        required: false
        description: 'Optional UUID that makes the request safely retriable. A replay keeps the cached payload immutable except for billing metadata: `credits_used` becomes 0, `idempotent_replay` becomes true, and `credits_remaining` is refreshed to the current balance. A known current balance appears in both the body and `X-Credits-Remaining` header; no balance row resolves to 0. On a transient lookup failure, body `credits_remaining` is null and `X-Credits-Remaining` is omitted. Scoped per account with a 24-hour TTL.'
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          headers:
            X-Credits-Used:
              description: Net credits charged for this response. Idempotency replays report 0.
              schema:
                type: integer
                minimum: 0
            X-Credits-Remaining:
              description: Current balance when known. On an idempotency replay, this header is omitted when the balance lookup fails; body `credits_remaining` is null instead.
        

# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socialcrawl/refs/heads/main/openapi/socialcrawl-google-shopping-api-openapi.yml