Home Depot

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.

Quickstart

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

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"

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

4 endpoints available.

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

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:

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 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 for the field shapes and the labels you can add with label=, such as label=reports&reports=the battery drains quickly.

Next steps