# SocialCrawl API — walmart endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/walmart

## GET /v1/walmart/product
Get a Walmart product by id
Credit cost: 5 (advanced)
Parameters:
- product_id (required) — Walmart product id. Either the numeric item id from the product URL (walmart.com/ip/<name>/17835006350) or the alphanumeric catalog id (34J2GQ9D9TFM). Both resolve to the same product.
- country (optional, enum: US | CA) — Walmart marketplace as a two-letter country code: US (walmart.com, default) or CA (walmart.ca). A product id from one marketplace will not resolve in the other.
curl "https://www.socialcrawl.dev/v1/walmart/product?product_id=17835006350" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/walmart/reviews
Get Walmart product reviews
Credit cost: 5 (advanced)
Parameters:
- product_id (required) — Walmart product id, numeric or alphanumeric. The same id accepted by GET /v1/walmart/product.
- page (optional, integer) — Page number, starting at 1. Prefer the universal cursor parameter.
- limit (optional, integer) — Reviews per page, 1 to 50. Defaults to 10. Honoured exactly.
- sort (optional, enum: relevancy | recent | rating_high_low | rating_low_high) — Which reviews to return: relevancy (default), recent, rating_high_low, or rating_low_high. Changes the selection but does not guarantee the returned page is ordered; sort client-side if you need a strict order.
- rating (optional, integer) — Return only reviews with this exact star rating, 1 to 5. Applied exactly.
- country (optional, enum: US | CA) — Walmart marketplace as a two-letter country code: US (walmart.com, default) or CA (walmart.ca). A product id from one marketplace will not resolve in the other.
curl "https://www.socialcrawl.dev/v1/walmart/reviews?product_id=17835006350" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/walmart/search
Search Walmart products by keyword
Credit cost: 5 (advanced)
Parameters:
- query (required) — Search keyword or phrase.
- page (optional, integer) — Page number, starting at 1. Prefer the universal cursor parameter.
- sort_by (optional, enum: best_match | price_low | price_high | best_seller | top_rated) — Result ordering: best_match (default), price_low, price_high, best_seller, or top_rated.
- min_price (optional, string) — Lowest price to include. Must be below max_price when both are set. Applied by Walmart and approximate: it narrows the result set but occasionally returns a row outside the bound, so filter on product.price.current if you need a hard limit.
- max_price (optional, string) — Highest price to include. Must be above min_price when both are set. Applied by Walmart and approximate: it narrows the result set but occasionally returns a row outside the bound, so filter on product.price.current if you need a hard limit.
- zip_code (optional, string) — ZIP code used to localise availability, pickup, and shipping options. Walmart pricing and stock are store-level, so results differ by location.
- state (optional, string) — Two-letter US state code used to localise results (for example CA, NY).
- store_id (optional, string) — Walmart store id, to restrict results to one physical store's assortment.
- facet (optional, string) — Opaque refinement token taken from a previous response's facet data (for example a brand or category filter).
- country (optional, enum: US | CA) — Walmart marketplace as a two-letter country code: US (walmart.com, default) or CA (walmart.ca). A product id from one marketplace will not resolve in the other.
curl "https://www.socialcrawl.dev/v1/walmart/search?query=airpods pro" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/walmart/category
Browse Walmart products in a category
Credit cost: 5 (advanced)
Parameters:
- category_id (required) — Walmart category id, for example 3944 for Electronics. Category ids and their URLs are returned in the categories array of GET /v1/walmart/product.
- page (optional, integer) — Page number, starting at 1. Prefer the universal cursor parameter.
- sort_by (optional, enum: best_match | price_low | price_high | best_seller | top_rated) — Result ordering: best_match (default), price_low, price_high, best_seller, or top_rated.
- min_price (optional, string) — Lowest price to include. Must be below max_price when both are set. Applied by Walmart and approximate: it narrows the result set but occasionally returns a row outside the bound, so filter on product.price.current if you need a hard limit.
- max_price (optional, string) — Highest price to include. Must be above min_price when both are set. Applied by Walmart and approximate: it narrows the result set but occasionally returns a row outside the bound, so filter on product.price.current if you need a hard limit.
- zip_code (optional, string) — ZIP code used to localise availability, pickup, and shipping options. Walmart pricing and stock are store-level, so results differ by location.
- state (optional, string) — Two-letter US state code used to localise results (for example CA, NY).
- store_id (optional, string) — Walmart store id, to restrict results to one physical store's assortment.
- facet (optional, string) — Opaque refinement token taken from a previous response's facet data (for example a brand or category filter).
- country (optional, enum: US | CA) — Walmart marketplace as a two-letter country code: US (walmart.com, default) or CA (walmart.ca). A product id from one marketplace will not resolve in the other.
- limit (optional, integer) — Products per page, 1 to 100. Defaults to 40. Enforced by SocialCrawl: the page is trimmed to exactly this many rows.
curl "https://www.socialcrawl.dev/v1/walmart/category?category_id=3944" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/walmart/offers
Get every seller offering a Walmart product
Credit cost: 5 (advanced)
Parameters:
- product_id (required) — Walmart product id, numeric or alphanumeric. The same id accepted by GET /v1/walmart/product.
- country (optional, enum: US | CA) — Walmart marketplace as a two-letter country code: US (walmart.com, default) or CA (walmart.ca). A product id from one marketplace will not resolve in the other.
curl "https://www.socialcrawl.dev/v1/walmart/offers?product_id=17835006350" \
  -H "x-api-key: sc_your_api_key_here"