# Home Depot (/docs/home_depot)

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

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 that stock.

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 are Home Depot's online price and do not change with `store_id`: in
  our comparison on 28/09/2026 across four stores in three states, every shared
  item had the same current and original price. `store_id` localises stock and
  pickup. In-store-only shelf markdowns are not in this data. Get a store id from
  [`/v1/home_depot/stores`](#find-a-store).

## 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 stock 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`, `product.availability` and `product.ext.promotion`.

To turn a ZIP code into a store, call [`/v1/home_depot/stores`](#find-a-store) first and pass the store's `id` as `store_id`. Each row's `store_inventory` then marks that store with `is_selected_store`, and `availability` says whether any fulfilment path has the item in stock.

## Markdowns and clearance

When Home Depot publishes a markdown online, the row carries it under `product.ext.promotion`, on both `search` and `product`:

| Field | Type | Meaning |
| --- | --- | --- |
| `label` | `string` or `null` | Home Depot's Savings Center label, for example `Clearance` or `Special Buys` |
| `amount_off` | `number` or `null` | Dollars off `price.original`; null when nothing is off |
| `percent_off` | `number` or `null` | Percentage off `price.original`; null when nothing is off |

`price.original` is the price before that markdown, and equals `price.current` when there is none. `promotion` is `null` on a row without one. A Special Buy can carry the label with no amount off. When Home Depot withholds a price until checkout, `price.current` is `null` and `product.ext.price_note` says why, for example `see final price in cart`.

These are online markdowns, so they are the same at every store. There is no clearance filter: a keyword such as `clearance power tools` surfaces labelled rows, and you keep the ones whose `promotion.label` is `Clearance`.

## 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 at each location that can fulfil the item. `store_id` changes that stock figure and pickup availability, not the price.

Home Depot lists one location per fulfilment path, so a row is not always a store. A typical response has three rows: the pickup store, an express-delivery location and a ship-to-home location. Each row carries:

| Field | Type | Meaning |
| --- | --- | --- |
| `store_id` | `string` | Location id. `product` echoes the format you sent (`0159` stays `0159`); `search` drops the leading zero (`0723` comes back as `723`) |
| `store_name` | `string` or `null` | Store name; null on delivery locations |
| `state` | `string` or `null` | US state of the location |
| `in_stock` | `boolean` or `null` | Whether the location has stock |
| `quantity` | `number` or `null` | Units available at the location |
| `fulfillment` | `string` or `null` | `pickup` or `delivery` |
| `service` | `string` or `null` | For example `bopis`, `express delivery` or `sth` |
| `location_type` | `string` or `null` | `store` or `online` |
| `is_selected_store` | `boolean` or `null` | `true` on the store the request was localised to |

`search` rows carry the same `store_inventory`. Only a `bopis` row with `location_type` `store` is stock on that store's shelf. A `boss` row is online stock that can be shipped to the store for pickup, and `sth` is ship to home from an online warehouse.

To find the store you asked for, read `is_selected_store`. Do not match ids numerically: a delivery location can share digits with a store number, and `0121` is not store `121`. If every row reports `null` for the flag, the selected store is the `pickup` row whose `store_id` equals the `store_id` you sent, compared as an exact string. An unknown `store_id` returns a free `400` naming it.

## 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

**Shelf counts 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 are online prices.** They did not vary by store in any comparison we have run, so a store's own shelf markdown is not visible here. Compare against a competitor's online price, not a store receipt.

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

## Labels

`/v1/home_depot/reviews` labels each review by default, at no extra credit: `sentiment` (read from the words, never the stars, with `rating_mismatch` when the two clearly disagree) and `issue` (the main problem the review reports) on `computed.labels`. Send `judgments=off` for the page without them. See [Labels](/docs/labels.md) for the field shapes and the labels you can add with `label=`, such as `label=reports&reports=the battery drains quickly`.

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