SocialCrawl Home Depot API

openapi: 3.2.0
info:
  title: SocialCrawl Home Depot 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: home_depot
  description: Home_depot endpoints
paths:
  /home_depot/product:
    get:
      summary: Get a Home Depot product by item id or URL
      description: 'Returns full product detail for a Home Depot item: title, brand, model number, UPC, description, highlight bullets, current and original price, star rating with its 1-5 histogram, review count, the image gallery, a grouped specification table, and stock status. It also returns per-store inventory under product.ext.store_inventory, giving the actual unit count on the shelf at each nearby store, which is the field nothing else in this API sells. Pass store_id or zipcode to localise pricing and that inventory. For the review text call GET /v1/home_depot/reviews with the same item id.'
      tags:
      - home_depot
      operationId: get_home_depot_product
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      x-socialcrawl-oneOf:
      - - item_id
        - url
      parameters:
      - name: item_id
        in: query
        required: false
        description: 'Home Depot internet number (item id), the numeric id at the end of a homedepot.com product URL: homedepot.com/p/<name>/326680222 is item id 326680222. Pass url instead if you would rather hand over the whole product URL. (one of: item_id, url; at least one required)'
        schema:
          type: string
      - name: url
        in: query
        required: false
        description: 'Full Home Depot product page URL, used instead of item_id. The item id is extracted from it. (one of: item_id, url; at least one required)'
        schema:
          type: string
      - name: store_id
        in: query
        required: false
        description: Home Depot store number used to localise price, stock, and pickup availability, for example 121.
        schema:
          type: string
      - name: zipcode
        in: query
        required: false
        description: Five-digit US ZIP code used to localise delivery options and pricing, for example 30301.
        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.
              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:
                      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
                      _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.
                  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
                required:
                - success
                - platform
                - endpoint
                - data
                - credits_used
                - credits_remaining
                - request_id
                - cached
        '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'
  /home_depot/reviews:
    get:
      summary: Get Home Depot product reviews
      description: 'Returns written customer reviews for a Home Depot product, 20 per page and up to 100, each with the review text, star rating, reviewer name, submission date, verified-purchaser flag, helpful-vote count, reviewer photos, and any manufacturer reply. This is the fastest and most complete review surface in the API: pages do not overlap, the review total is stable across pages, and every one of the nine review fields is populated, so a full crawl is deterministic. Pass the returned cursor back until has_more is false.'
      tags:
      - home_depot
      operationId: get_home_depot_reviews
      security:
      - ApiKeyAuth: []
      x-credit-tier: advanced
      x-credit-cost: 5
      parameters:
      - name: item_id
        in: query
        required: true
        description: 'Home Depot internet number (item id), the numeric id at the end of a homedepot.com product URL: homedepot.com/p/<name>/326680222 is item id 326680222. Pass url instead if you would rather hand over the whole product URL.'
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: 'Page number, starting at 1. Prefer the universal cursor parameter. Native upstream cursor param. Send the universal `cursor` instead: the API maps it to this name for you.'
        deprecated: true
        schema:
          type: integer
          minimum: 1
          maximum: 51
      - name: items_per_page
        in: query
        required: false
        description: Reviews per page, 1 to 100. Defaults to 20.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: rating
        in: query
        required: false
        description: Return only reviews with this star rating, 1 to 5.
        schema:
          type: integer
          minimum: 1
          maximum: 5
      - name: sort_by
        in: query
        required: false
        description: 'Review ordering: helpful (default), newest, oldest, photos_first, highest_rating, or lowest_rating.'
        schema:
          type: string
          enum:
          - helpful
          - newest
          - oldest
          - photos_first
          - highest_rating
          - lowest_rating
      - name: search_text
        in: query
        required: false
        description: Return only reviews whose text contains these words, for example easy to use.
        schema:
          type: string
      - name: verified_only
        in: query
        required: false
        description: Set true to return only reviews written by verified purchasers.
        schema:
          type: boolean
      - name: cursor
        in: query
        required: false
        description: 'Universal pagination cursor. Send `pagination.next_cursor` from the previous response back verbatim: the API maps it to this endpoint''s native `page` (page style). You never construct, decode, or look up a cursor. Omit it for page 1.'
        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.
              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 review wrappers ({ review })
                        items:
                          type: object
                          description: Canonical review wrapper
                          properties:
                            review:
                              type: object
                              description: Canonical Review object (shared across commerce platforms)
                              properties:
                                id:
                                  type: string
                                  description: Review ID (parsed from the review URL when not first-class)
                                entity_id:
                                  type:
                                  - string
                                  - 'null'
                                  description: ID of the reviewed entity (e.g. the Amazon ASIN)
                                url:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at review.url
                                title:
                                  type:
                                  - string
                                  - 'null'
                                  description: String at review.title
                                text:
                                  type:
                                  - string
                                  - 'null'
                                  description: Full review body
                                rating:
                                  type: object
                                  description: Star rating (value + max)
                                  properties:
                                    value:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at review.rating.value
                                    max:
                                      type:
                                      - integer
                                      - 'null'
                                      description: Numeric at review.rating.max
                                author:
                                  type: object
                                  description: 'Nested object: review.author'
                                  properties:
                                    name:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at review.author.name
                                    avatar_url:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at review.author.avatar_url
                                    url:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at review.author.url
                                    location:
                                      type:
                                      - string
                                      - 'null'
                                      description: String at review.author.location
                                  

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