# Walmart Suggest

## Overview

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

## Description

Get Walmart.com search autocomplete suggestions for a keyword via browser rendering, with optional US ZIP code localization.

## 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/suggest' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Suggest for 'apples' near ZIP 95829

```json
{
  "results": [
    {
      "url": "query=apples&typeahead=apples",
      "type": "QUERY",
      "image_url": "https://i5.walmartimages.com/asr/bcfd9451-a73b-411f-84e3-1d866f833ae8.3e996f05a24facfa2ac526d6c631401d.jpeg",
      "analytics_fm": 5,
      "display_name": "apples"
    },
    {
      "url": "query=applesauce&typeahead=apples",
      "type": "QUERY",
      "image_url": "https://i5.walmartimages.com/asr/d71c007b-3ae2-433f-9ca2-41906af71500.bff31e2bb8bdfddd3bd46ae00f50135d.jpeg",
      "analytics_fm": 5,
      "display_name": "applesauce"
    },
    {
      "url": "query=apple%20juice&typeahead=apples",
      "type": "QUERY",
      "image_url": "https://i5.walmartimages.com/asr/34a4bc66-9cdb-404c-8665-b6435742ed45.3402c97169db76e6c3784d67cc1ad581.jpeg",
      "analytics_fm": 5,
      "display_name": "apple juice"
    }
  ]
}
```

## Documentation

## Overview
Return search autocomplete suggestions from the Walmart.com typeahead: the same query expansions shoppers see while typing in the search bar.

Walmart injects suggestions dynamically after JavaScript runs. Piloterr uses **website rendering** to load walmart.com in a browser, trigger the typeahead for your keyword, and return structured suggestion objects with display labels, thumbnail images, and internal query strings.

Pair this endpoint with **Walmart Search** (full results page) and **Walmart Product** (PDP details) to build a complete discovery pipeline.

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

With optional ZIP localization:
```
GET https://api.piloterr.com/v2/walmart/suggest?query=apples&zipcode=95829
```

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

{"query": "apples"}
```

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Partial or full search keyword (e.g. `apples`) |
| `zipcode` | string | no | Optional 5-digit US ZIP code for localized store context |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | Autocomplete suggestions returned by Walmart |
| `results[].display_name` | string | Label shown in the typeahead dropdown |
| `results[].url` | string | Internal query string (e.g. `query=applesauce&typeahead=apples`) |
| `results[].type` | string | Suggestion type (typically `QUERY`) |
| `results[].image_url` | string | Thumbnail image for the suggested category or product |
| `results[].analytics_fm` | number | Walmart analytics metadata attached to the suggestion |

## Workflow
1. **Suggest**: discover related queries from a partial keyword
2. **Search**: pass `https://www.walmart.com/search?q=<term>` to get product cards
3. **Product**: pass any result `/ip/` URL for full PDP data

## Notes
- Returns query-level suggestions, not full product listings.
- `zipcode` is optional: omit it when you only need generic query suggestions.
- When provided, the ZIP code affects localized store and inventory context on walmart.com.
- Build the search URL from a suggestion: `https://www.walmart.com/search?q=<display_name>`.
- Costs **2 credits** per call (browser rendering).

## Main use cases
- Power typeahead UIs with live Walmart search suggestions
- Discover high-intent query expansions from partial keywords
- Feed keyword research and SEO pipelines for US grocery and retail
- Localize suggestion context by ZIP code when store-level intelligence is needed