# Home Depot (/docs/home_depot)

Home Depot keyword search, product detail with per-store shelf counts, customer reviews, and a store locator that turns a ZIP code into localised pricing

Home Depot products, reviews and stores behind the same 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 `stores` turns a postcode into the store id that localises every price on the platform.

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

Products are keyed on the **internet number**, the numeric id at the end of a product URL. In `homedepot.com/p/<name>/100333077` the item id is `100333077`.

  Prices and stock without a `store_id` are national catalogue figures, not what
  a shopper standing in a store sees. Get a store id from
  [`/v1/home_depot/stores`](#find-a-store), then set `store_id` on both sides of
  a price comparison, or on neither.

## Quickstart

### Find products by keyword

`search` is the keyword-to-item-id resolver for the rest of the platform. It returns 24 products a page.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/home_depot/search?query=paver" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read the product and its reviews

Full detail including per-store shelf counts, then the review text.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/home_depot/product?item_id=100333077" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/home_depot/reviews?item_id=100333077" \
  -H "x-api-key: YOUR_API_KEY"
```

### Localise it to a store

Turn a ZIP into a store id, then pass that id back into `search` or `product`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/home_depot/stores?query=95032" \
  -H "x-api-key: YOUR_API_KEY"

curl "https://www.socialcrawl.dev/v1/home_depot/search?query=paver&store_id=1009" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Search

`GET /v1/home_depot/search` takes `query` plus two optional parameters: `page` (1 to 30) and `store_id`. It returns 24 products a page with item id, title, brand, model number, current and original price, rating, review count, images, department and stock status, and a `total` that holds steady across pages.

It takes no sort or filter parameters. If you send `sort_by`, `items_per_page`, `brand`, `min_price`, `max_price`, `in_stock` or `zipcode` you get a `400` naming the parameter rather than a silently unfiltered page, because a filter that is quietly ignored is worse than an error: you cannot tell it happened. Filter and sort on the returned rows instead, which carry `product.price.current`, `product.brand`, `product.rating` and `product.availability`.

## Product detail

`GET /v1/home_depot/product` takes `item_id` or the full product `url`, plus an optional `store_id`. Give it the URL and the item id is extracted for you.

The field nothing else in this API sells is `product.ext.store_inventory`: the actual unit count on the shelf at each nearby store. `store_id` changes the price, that stock figure and pickup availability.

## Reviews

`GET /v1/home_depot/reviews` takes `item_id` and returns the ten most relevant reviews, each with the text, star rating, reviewer name, location, submission date, verified-purchaser flag, helpful-vote count and photos. `total` reports the full number of reviews on the product, so you can always see how many exist beyond the ten returned.

This is a single page. The upstream exposes no paging parameter, so there is no cursor to follow.

## Find a store

`GET /v1/home_depot/stores` takes a five-digit US ZIP as `query` and returns the 20 nearest stores with store id, name, full address, phone, distance in miles and seven days of opening hours. Store data changes rarely, so it is 1 credit and heavily cached.

## Platform notes

**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.

**Search pages can repeat a row.** Home Depot's own result ordering shifts slightly between pages, so consecutive pages occasionally re-serve a product. We de-duplicate across a paging session for you, and a page that de-duplicates to nothing is not charged.

**US only.** Prices are US dollars and there is no marketplace selector.

**Category browsing is temporarily withdrawn.** `GET /v1/home_depot/category` returns a free `503` while its data source is re-established. Use `search` with a descriptive keyword in the meantime, and see the [changelog](/changelog) for its status.

## Next steps

- [Pagination](/docs/pagination.md): The universal cursor, and how to walk a search to the end.
- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [Walmart](/docs/walmart.md): Store-level pricing and marketplace seller offers.
- [Wayfair](/docs/wayfair.md): The same shapes for home and furniture, keyed on SKU.