Search Results

The Search endpoint runs a keyword search against one Walmart store and returns structured product listings, with the prices and availability that store actually offers. Sponsored placements are included and flagged, so you can keep or drop them yourself.

Endpoint

GET https://api.scrape.do/plugin/walmart/search

Each successful request costs 10 credits. Failed requests are never charged.

Input Parameters

Parameter	Type	Required	Description
`token`	string	*	Your Scrape.do API authentication token
`q`	string	*	Search keyword (URL-encoded). `query` is accepted as an alias.
`store`	integer	*	Walmart store id to scope results to. Provide exactly one of `store` or `zipcode`.
`zipcode`	string	*	5-digit US ZIP code to scope results to. Provide exactly one of `store` or `zipcode`.
`timeout`	integer		Per-request timeout in milliseconds (default: system maximum)

Response Parameters

Field	Type	Description
`store`	object	The store this response reflects
`query`	string	The keyword that was searched
`total_results`	number	Total matches Walmart reports for the keyword, across all pages
`page`	number	Current page number
`total_pages`	number	Highest page available for this keyword
`has_more_pages`	boolean	Whether Walmart reports further results after this page
`results`	array	The search results

Store Object Fields

Field	Type	Description
`store_id`	string	The store id this response is scoped to
`city`	string	City the store is in
`state`	string	Two-letter state code
`postal_code`	string	ZIP code for the store's location

Result Object Fields

Field	Type	Description
`position`	number	1-based position in this response
`item_id`	string	Walmart item id. Pass this to `/plugin/walmart/product`
`name`	string	Product title
`brand`	string	Brand name, when Walmart supplies one
`url`	string	Product page URL
`image`	string	Product thumbnail URL
`price`	number	Current price at this store. `null` when Walmart shows no price
`list_price`	number	Pre-discount price, present only when the item is discounted
`currency`	string	Currency code (`USD`)
`rating`	number	Average customer rating
`reviews_count`	number	Number of reviews
`seller`	string	Who sells the item — `Walmart.com` or a marketplace seller's name
`availability`	string	Stock status at this store, e.g. `IN_STOCK`, `OUT_OF_STOCK`
`fulfillment`	array	Fulfillment methods offered, lowercased — e.g. `["delivery","pickup"]`
`sponsored`	boolean	`true` for paid placements
`category`	string	Walmart's category path for the item

results holds the main search results for your keyword, including sponsored placements marked "sponsored": true. Merchandising carousels that Walmart mixes into the same page — "trending", "highly rated" — are excluded, because they do not answer the keyword you searched for.

Example Usage

Step 1: Pick a Store and a Keyword

Target by store id when you are tracking a fixed location:

curl "https://api.scrape.do/plugin/walmart/search?q=milk&store=1735&token=YOUR_TOKEN"

Or by ZIP code when you care about an area rather than a specific store:

curl "https://api.scrape.do/plugin/walmart/search?q=milk&zipcode=60074&token=YOUR_TOKEN"

Step 2: Read the Response

{
  "store": {
    "store_id": "1735",
    "city": "Deer Park",
    "state": "IL",
    "postal_code": "60074"
  },
  "query": "milk",
  "total_results": 413,
  "page": 1,
  "total_pages": 19,
  "has_more_pages": true,
  "results": [
    {
      "position": 1,
      "item_id": "23619910",
      "name": "Lactaid Whole Milk, 96 oz",
      "brand": "Lactaid",
      "url": "https://www.walmart.com/ip/Lactaid-Whole-Milk-96-oz/23619910",
      "image": "https://i5.walmartimages.com/seo/Lactaid-Whole-Milk-96-oz.jpeg",
      "price": 6.24,
      "list_price": null,
      "currency": "USD",
      "rating": 4.6,
      "reviews_count": 1183,
      "seller": "Walmart.com",
      "availability": "IN_STOCK",
      "fulfillment": ["pickup", "delivery"],
      "sponsored": false,
      "category": "Food/Dairy Eggs & Cheese/Milk"
    }
  ]
}

Step 3: Chain Into Product Lookups

Each result's item_id is what the product endpoint takes, so a search feeds product lookups directly:

curl "https://api.scrape.do/plugin/walmart/product?item=23619910&store=1735&token=YOUR_TOKEN"

Keep the same store across both calls — that is what makes the price on the product page match the price you saw in the search results.

Empty Results

A keyword that genuinely matches nothing at that store returns 200 with an empty array, not an error:

{
  "store": { "store_id": "1735", "city": "Chicago", "state": "IL", "postal_code": "60620" },
  "query": "zxqwvbnmasdfghjkl123",
  "total_results": 0,
  "page": 1,
  "total_pages": 0,
  "has_more_pages": false,
  "results": []
}

Error Responses

Status	Body	Cause
400	`{"error":"token is required"}`	Missing token
400	`{"error":"q (search query) is required"}`	Missing `q` / `query`
400	`{"error":"exactly one of store or zipcode is required"}`	Both or neither of `store` / `zipcode` were provided
400	`{"error":"store must be numeric"}`	`store` is not numeric
400	`{"error":"zipcode must be a 5-digit US zip"}`	`zipcode` is not a valid 5-digit US ZIP
400	`{"error":"timeout is invalid"}`	`timeout` is not an integer
400	Unsupported store id	This endpoint does not cover that store id. Pass `zipcode` instead, or contact support to have your store added.
502	`{"error":"walmart-search plugin failure.","message":"…"}`	Could not get a valid response for this store or ZIP. Not charged.