# Walmart API scraper — search Walmart.com products with filters, sort & pagination, full product detail (price, specifications, variants, seller, availability), customer reviews (rating breakdown + review texts), and category/department browse. No account required.

> Search Walmart.com by keyword → a paginated, sortable list of products with item id, name, current & list price, savings, star rating + review count, availability, seller, category, fulfillment, image and the product link. Narrow with min_price/max_price and sort. Note: `brand` is a separate field only where Walmart itself splits it out — measured 65/65 on backpacks and 57/57 on sneakers, but 0/53 on laptops and 0/49 on TVs, where Walmart instead carries the brand inside the product name ('HP 14 inch…'). Use product_detail when you need brand as a guaranteed field.
> ReefAPI engine `walmart` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/walmart/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /walmart/v1/search — 2 credits
Search Walmart.com by keyword → a paginated, sortable list of products with item id, name, current & list price, savings, star rating + review count, availability, seller, category, fulfillment, image and the product link. Narrow with min_price/max_price and sort. Note: `brand` is a separate field only where Walmart itself splits it out — measured 65/65 on backpacks and 57/57 on sneakers, but 0/53 on laptops and 0/49 on TVs, where Walmart instead carries the brand inside the product name ('HP 14 inch…'). Use product_detail when you need brand as a guaranteed field.

**Parameters:**
- `query` (string, required) — What to search for on Walmart.com (product keywords, brand, or model).
- `sort` (enum, optional, default "best_match") — Result ordering. [one of: best_match, price_low, price_high, best_seller, rating_high, new]
- `page` (integer, optional, default 1) — Result page (~40-55 products per page; paginate with page += 1). The response's `max_page` is the last page Walmart will serve for the query. Walmart repeats SPONSORED tiles across pages (measured: 12 repeats page1↔page2, 11 of them sponsored); filter on `sponsored == false` for a duplicate-free paginated set.
- `max_results` (integer, optional) — How many products to return (1-400). Walmart serves about 40-55 per page, so asking for more than that fetches the further pages automatically — they are fetched TOGETHER, so 200 results cost roughly the time of one page rather than five. 400 is Walmart's real ceiling: it stops serving products after page 10, measured — note that Walmart's own `max_page` claims 13-14 and is wrong, so do not size a job from it. OMIT IT to get exactly one page, exactly as this action behaves today — `page` on its own is completely unchanged.
- `min_price` (number, optional) — Lowest price to include (USD).
- `max_price` (number, optional) — Highest price to include (USD).
- `facet` (string, optional) — Advanced: a raw Walmart facet token (e.g. a brand/department filter from a category page) appended to the search as &facet=. Escape hatch for power users; omit for a plain keyword search.

**Returns:** results[]{item_id, name, brand, price, list_price, savings_amount, currency, rating, review_count, availability, availability_display, in_stock, seller, seller_id, category, badge, fulfillment{methods,earliest_date}, price_range, min_price, image, url, sponsored} + total + count + page + max_page + related_searches

**Example request body:**
```json
{
  "query": "laptop"
}
```

### POST /walmart/v1/product_detail — 2 credits
Full product record by Walmart item id (or product URL): name, brand, model, UPC, manufacturer part number, current & list price, availability, seller, average rating + review count, short & long descriptions, the full specification table, product highlights, every variant with its resolved attributes (colour/size/…), the category breadcrumb, return policy, fulfillment and the gallery images.

**Parameters:**
- `item_id` (string, optional) — Walmart item id — the number in a walmart.com/ip/<id> URL, or a search result's `item_id`. Provide item_id OR url.
- `url` (string, optional) — Full walmart.com product page URL (alternative to item_id; the id is parsed from /ip/<id>).

**Returns:** product{item_id, name, brand, model, upc, manufacturer_part_number, type, price, list_price, currency, availability, seller, seller_id, condition, rating, review_count, short_description, long_description, specifications[], highlights[], variants[]{id,usItemId,attributes[],price,availability,url,image}, variant_options[], category_path[], return_policy{}, fulfillment{}, warnings[], images[], url}

### POST /walmart/v1/reviews — 1 credit
Customer reviews for a Walmart product by item id (or product URL): the average rating, total review count, recommended-percentage, the 5★→1★ rating distribution and percentages, the most-mentioned aspects, and the review texts (rating, title, body, date, helpful counts, verified-purchase, purchased variant, photos).

**Parameters:**
- `item_id` (string, optional) — Walmart item id — the number in a walmart.com/ip/<id> URL, or a search result's `item_id`. Provide item_id OR url.
- `url` (string, optional) — Full walmart.com product page URL (alternative to item_id; the id is parsed from /ip/<id>).
- `max_results` (integer, optional, default 20) — How many review texts to return (10 per Walmart page, fetched concurrently). The rating distribution is always the full-catalog total. Only `reviews_with_text_count` of the total ratings actually carry text.

**Returns:** average_rating + total_review_count + reviews_with_text_count + recommended_percentage + rating_distribution{5,4,3,2,1} + rating_percentages + aspects[] + reviews[]{review_id, rating, title, text, date, helpful_positive, helpful_negative, verified_purchase, recommended, variant[], photos[]}

### POST /walmart/v1/category — 2 credits
Browse a Walmart category / department by its query term (e.g. 'coffee maker', '4k tv') → the same product grid as search, framed as a category browse with the related category searches surfaced. Paginated and sortable.

**Parameters:**
- `query` (string, required) — The category/department to browse (a Walmart department name or product-class keyword).
- `sort` (enum, optional, default "best_match") — Result ordering. [one of: best_match, price_low, price_high, best_seller, rating_high, new]
- `page` (integer, optional, default 1) — Result page (~40-55 products per page; paginate with page += 1). The response's `max_page` is the last page Walmart will serve for the query. Walmart repeats SPONSORED tiles across pages (measured: 12 repeats page1↔page2, 11 of them sponsored); filter on `sponsored == false` for a duplicate-free paginated set.
- `max_results` (integer, optional) — How many products to return (1-400). Walmart serves about 40-55 per page, so asking for more than that fetches the further pages automatically — they are fetched TOGETHER, so 200 results cost roughly the time of one page rather than five. 400 is Walmart's real ceiling: it stops serving products after page 10, measured — note that Walmart's own `max_page` claims 13-14 and is wrong, so do not size a job from it. OMIT IT to get exactly one page, exactly as this action behaves today — `page` on its own is completely unchanged.
- `min_price` (number, optional) — Lowest price to include (USD).
- `max_price` (number, optional) — Highest price to include (USD).

**Returns:** results[]{item_id, name, price, rating, review_count, availability, seller, image, url} + total + count + page + max_page + category + related_searches

**Example request body:**
```json
{
  "query": "4k tv"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=walmart
- Human docs page: https://reefapi.com/docs/walmart
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt