Walmart Search API

GET | POST /v1/walmart/search

Send parameters as a query string with GET, or as a JSON body with POST. Both are equivalent.

Request

curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks&priceMax=30" \
  -H "x-api-key: $APINOA_API_KEY"

Parameters

Parameter	Type	Required	Notes
`query`	string	yes	Keywords to search for. Required: image search is not available on Walmart, so a keyword query is the only way to search.
`brands`	string list		Brand names as the marketplace spells them, e.g. brands=Nike,Adidas.
`categoryId`	string		Narrow to one category, by the marketplace's own id. Opaque and per-marketplace; take it from Product.category[].id or from a result's `facets`.
`facets`	string \| object list		Narrowings taken from a result's `facets`, e.g. facets=Color:Black. The escape hatch for filters the typed vocabulary has no word for; prefer a typed parameter where one exists.
`page`	integer		1-based results page. There is no `pageSize` — the results page is server-fixed at about 50 organic items — and no `cursor`, since paging here is by number.
`priceMax`	number ≥ 0		Highest price to return, in decimal major units.
`priceMin`	number ≥ 0		Lowest price to return, in decimal major units.
`ratingMin`	number 0–5		Lowest average star rating to return, on the marketplace's own 0-5 scale.
`region`	string		Buyer country as ISO 3166-1 alpha-2; sets availability, shipping and price.
`sort`	enum		Result ordering: `best_match`, `price_asc`, `price_desc`, `newly_listed` or `best_seller`. Defaults to `best_match`, Walmart's own relevance ordering. `best_match` `price_asc` `price_desc` `newly_listed` `best_seller`

The same parameters, and every response type, are in the OpenAPI document.

Response

Returns SearchResult in data. A real response, shortened: arrays keep their first entries and long text is cut.

{
  "success": true,
  "data": {
    "marketplace": "walmart",
    "query": "wool socks",
    "page": {
      "index": 1,
      "size": 47,
      "total": 4888
    },
    "items": [
      {
        "marketplace": "walmart",
        "id": "344144554",
        "title": "Genuine Dickies Men's Wool Thermal Crew Sock, 3 Pack, Shoe Size 6-12",
        "price": {
          "currency": "USD",
          "amount": 15.98
        },
        "brand": "Dickies",
        "url": "https://www.walmart.com/ip/Genuine-Dickies-Men-s-Wool-Thermal-Crew-Sock-3-Pack-Shoe-Size-6-12/344144554",
        "imageUrl": "https://i5.walmartimages.com/seo/Genuine-Dickies-Men-s-Wool-Thermal-Crew-Sock-3-Pack-Shoe-Size-6-12_7f83249a-fb07-4602-…",
        "seller": {
          "name": "Walmart.com",
          "id": "F55CDC31AB754BB68FE0B39041159D63"
        },
        "rating": {
          "average": 4.7,
          "count": 552
        },
        "status": "In stock",
        "inStock": true,
        "sponsored": true,
        "category": [
          {
            "id": "5438",
            "name": "Clothing"
          },
          {
            "id": "133197",
            "name": "Mens Clothing"
          }
        ],
        "badges": [],
        "promotions": [],
        "attributes": []
      }
    ],
    "facets": [
      {
        "id": "suggested",
        "name": "Suggested",
        "kind": "select",
        "values": [
          {
            "value": "Merino Wool",
            "name": "Merino Wool"
          },
          {
            "value": "Crew",
            "name": "Crew"
          }
        ]
      },
      {
        "id": "brand",
        "name": "Brand",
        "kind": "select",
        "values": [
          {
            "value": "Loritta",
            "name": "Loritta"
          },
          {
            "value": "Wrangler",
            "name": "Wrangler"
          }
        ],
        "maps_to": "brands"
      }
    ]
  }
}

Errors

Status	Code	Meaning
400	`INVALID_PARAMS`	A parameter is missing, unknown or out of range. The message names it.
401	`UNAUTHORIZED`	The `x-api-key` header is missing, or the key is revoked or unknown.
402	`INSUFFICIENT_BALANCE`	The balance does not cover this call. Top up in the dashboard.
429	`MARKETPLACE_SATURATED`	Too many concurrent calls. Retry after the `Retry-After` seconds.
502	`UPSTREAM_ERROR`	The platform answered with something unusable. Retry with backoff.

Every code is listed in Errors. Failed calls are not billed.

Pricing

Price $0.001 per call. List price; the rate steps down above 1,000 calls a day.

Notes

ratingMin snaps to a band. Walmart filters by rating band ("4 – 5 Stars", "3 – 3.9 Stars"), so a request picks the lowest band that still satisfies it: 3.5 selects 4–5, and 4.5 sends no rating filter because no band can satisfy it.
Paging is by page. The page size is fixed at about 50 items, so there is no pageSize and no cursor.
Not supported: condition, freeShipping, inStock.

Search