# Walmart Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/walmart/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/walmart-search |

## Description

Scrape Walmart.com search result pages from a full URL and retrieve product cards with pricing, ratings, availability, and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/walmart/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search 'apples' on walmart.com

```json
{
  "results": [
    {
      "id": "40KH71FS6S1U",
      "url": "https://www.walmart.com/ip/Fresh-Rockit-Crisp-Sweet-Miniature-Apples-3lb-Tub/309762096?classType=REGULAR",
      "name": "Fresh Rockit, Crisp Sweet Miniature Apples, 3lb Tub",
      "type": "REGULAR",
      "brand": null,
      "image": "https://i5.walmartimages.com/seo/Fresh-Rockit-Crisp-Sweet-Miniature-Apples-3lb-Tub_de6d6d44-507a-43e4-9bd9-d86286473870.4d6dbcb5c200885859982510d4314077.jpeg?odnHeight=180&odnWidth=180&odnBg=FFFFFF",
      "price": 8.97,
      "price_info": {
        "unit_price": "$2.99/lb",
        "line_price_display": "$8.97"
      },
      "us_item_id": "309762096",
      "seller_name": "Walmart.com",
      "canonical_url": "/ip/Fresh-Rockit-Crisp-Sweet-Miniature-Apples-3lb-Tub/309762096?classType=REGULAR",
      "average_rating": 4.4,
      "fulfillment_type": "STORE",
      "is_sponsored_flag": true,
      "number_of_reviews": 2034,
      "availability_status_v2": {
        "value": "IN_STOCK",
        "display": "In stock"
      }
    },
    {
      "id": "2GZTW48YO9IV",
      "url": "https://www.walmart.com/ip/Fresh-Envy-Apples-3-lb-Bag/978115165?classType=REGULAR",
      "name": "Fresh Envy™ Apples, 3 lb Bag",
      "type": "REGULAR",
      "brand": null,
      "image": "https://i5.walmartimages.com/seo/Fresh-Envy-Apples-3-lb-Bag_d988dbde-f74a-4fde-a66f-b96569f9133b.87d9427485c1e5d8b3feaf0c0fde5834.jpeg?odnHeight=180&odnWidth=180&odnBg=FFFFFF",
      "price": 5.37,
      "price_info": {
        "unit_price": "$1.79/lb",
        "line_price_display": "$5.37"
      },
      "us_item_id": "978115165",
      "seller_name": "Walmart.com",
      "canonical_url": "/ip/Fresh-Envy-Apples-3-lb-Bag/978115165?classType=REGULAR",
      "average_rating": 4.2,
      "fulfillment_type": "STORE",
      "is_sponsored_flag": true,
      "number_of_reviews": 1172,
      "availability_status_v2": {
        "value": "IN_STOCK",
        "display": "In stock"
      }
    }
  ],
  "pagination": {
    "next": true,
    "page": 1,
    "total": 92,
    "max_page": 5
  }
}
```

## Documentation

## Overview
Extract product listing cards from any Walmart.com search results page (`walmart.com/search`). Pass a full search URL copied from the browser and receive structured results with titles, prices, unit prices, ratings, review counts, seller info, stock status, sponsorship flags, and pagination metadata.

Walmart search pages are JavaScript-driven single-page applications. Product cards and sponsored placements are rendered client-side after the page loads. Piloterr uses **website rendering** to open the search URL in a browser, wait for listings to appear, and extract structured JSON from the rendered page.

Use each result's `url` with the **Walmart Product** endpoint for full PDP data (specs, fulfillment, badges, images).

## Quickstart
```
GET https://api.piloterr.com/v2/walmart/search?query=https://www.walmart.com/search?q=apples
```

Or via POST:
```
POST https://api.piloterr.com/v2/walmart/search
Content-Type: application/json

{"query": "https://www.walmart.com/search?q=apples"}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full Walmart search URL from walmart.com |

## Supported URL formats
| Format | Example |
|---|---|
| Keyword search | `https://www.walmart.com/search?q=apples` |
| Paginated search | `https://www.walmart.com/search?q=apples&page=2` |
| Filtered search | Any walmart.com `/search` URL with sort, category, or facet params |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Product cards from the search results page |
| `results[].us_item_id` | string | Walmart numeric item ID |
| `results[].id` | string | Internal Walmart product identifier |
| `results[].name` | string | Product title |
| `results[].url` | string | Full product page URL (`/ip/`) |
| `results[].canonical_url` | string | Relative product URL path |
| `results[].image` | string | Product thumbnail URL |
| `results[].price` | number | Numeric price when available |
| `results[].price_info.line_price_display` | string | Formatted shelf price (e.g. `$8.97`) |
| `results[].price_info.unit_price` | string | Unit price label (e.g. `$2.99/lb`) |
| `results[].average_rating` | number | Average customer rating |
| `results[].number_of_reviews` | number | Total review count |
| `results[].seller_name` | string | Seller display name |
| `results[].availability_status_v2.value` | string | Stock status code (e.g. `IN_STOCK`) |
| `results[].is_sponsored_flag` | boolean | Whether the listing is a sponsored placement |
| `results[].fulfillment_type` | string | Fulfillment mode (e.g. `STORE`) |
| `pagination.page` | number | Current page number |
| `pagination.total` | number | Total matching products |
| `pagination.max_page` | number | Maximum page available |
| `pagination.next` | boolean | Whether a next page exists |

## Workflow
1. **Suggest**: discover query expansions from a partial keyword + ZIP
2. **Search**: scrape the search results page for product cards (this endpoint)
3. **Product**: fetch full PDP JSON from any result `url`

## Notes
- Always pass the full search URL copied from walmart.com (not just the keyword).
- Paginate by updating `page=` in the URL (e.g. `&page=2`).
- Results may include sponsored listings (`is_sponsored_flag: true`).
- Costs **2 credits** per call (browser rendering).

## Main use cases
- Monitor Walmart search rankings and sponsored placement for target keywords
- Build US retail price intelligence pipelines from live search pages
- Discover product URLs and `us_item_id` values at scale
- Track competitor visibility across category and keyword searches