# Home Depot (/docs/home_depot)



Home Depot [#home-depot]

Home Depot product records and customer reviews behind the same unified envelope and canonical
commerce schema as Amazon, Walmart, Target and eBay. Two things make this platform unusual:
`product` reports **how many units are physically on the shelf** at a given store, and `reviews`
returns the cleanest review pagination of any retailer here.

Base URL: `/v1/home_depot/...`

<Callout>
  There is no keyword search and no category browse on this platform — Home Depot exposes neither. You need an item id or a product URL to start. Prices and stock without a 

  `store_id`

   are national catalogue figures, not what a shopper sees in a store.
</Callout>

Getting started [#getting-started]

Every endpoint is a `GET` with query parameters and an `x-api-key` header. Products are
identified by the **internet number**, the numeric id at the end of a product URL:
`homedepot.com/p/<name>/326680222` is item id `326680222`.

```bash
# Product detail, priced and stocked for one store
curl "https://www.socialcrawl.dev/v1/home_depot/product?item_id=326680222&store_id=121" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"

# Its reviews, twenty per page
curl "https://www.socialcrawl.dev/v1/home_depot/reviews?item_id=326680222&sort_by=newest" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Both endpoints are 5 credits.

Product detail [#product-detail]

`GET /v1/home_depot/product` takes either `item_id` or the full product `url` — pass whichever
you already hold, and the item id is extracted from the URL for you. It returns title, brand,
model number, price, rating, specifications, images, and per-store stock counts.

Two optional parameters localise the answer. `store_id` is a Home Depot store number (for
example `121`) and it changes the price, the stock figure and pickup availability. `zipcode` is
a five-digit US ZIP and localises delivery options and pricing. Omit both and you get national
catalogue pricing, which is a different number from what a shopper standing in a store sees.

Reviews [#reviews]

`GET /v1/home_depot/reviews?item_id=…` returns twenty written reviews per page, each with the
full text, rating, reviewer, date, verified flag, helpful votes, photos, and any reply from the
manufacturer. This is the most complete review data in the API: pages do not overlap, the total
holds steady across a crawl, and every field is populated rather than sometimes-null.

Filters do real work here:

* `items_per_page` — 1 to 100, default 20
* `rating` — return only one star value
* `sort_by` — `helpful` (default), `newest`, `oldest`, `photos_first`, `highest_rating`,
  `lowest_rating`, `relevance`
* `search_text` — return only reviews whose text contains a phrase, such as `easy to use`
* `verified_only` — restrict to verified purchasers

`search_text` combined with `rating` is the fast way to answer a specific product question — the
one-star reviews mentioning a particular defect, for instance — without paging the whole set.

```bash
curl "https://www.socialcrawl.dev/v1/home_depot/reviews?item_id=326680222&rating=1&search_text=leak&verified_only=true" \
  -H "x-api-key: $SOCIALCRAWL_API_KEY"
```

Note that `reviews` takes `item_id` only — the URL shortcut is on `product`.

Endpoints [#endpoints]

<PlatformEndpoints platform="home_depot" />

Read this before you build [#read-this-before-you-build]

**There is no keyword search and no category browse on this platform.** Home Depot exposes
neither, so the way in is an item id or a product URL you already have. If you need to find
products by keyword first, use [`/v1/google_shopping/product-search`](/docs/google_shopping.md) or
[`/v1/google/search`](/docs/google.md) with `site:homedepot.com` in the query, and take the item id
off the resulting URL.

**Stock counts are per store and go stale fast.** The shelf figure is exactly as volatile as it
sounds. Treat it as a point-in-time reading rather than something to cache.

**Prices without a `store_id` are national.** If you are comparing against a competitor's
store-level price, set `store_id` on both sides or neither.

Notes [#notes]

* All endpoints use `GET` with query parameters
* Authentication via the `x-api-key` header
* Responses follow the unified SocialCrawl schema, shared with the other commerce platforms
* Reviews are page-paginated starting at `page=1`, and pages do not repeat rows
* Home Depot is a US retailer; prices are US dollars and there is no marketplace selector