> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopping API Quickstart

> Find products to buy, linked to store product pages, with the Parallel Shopping API

For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](https://docs.parallel.ai/llms-full.txt). You may also fetch any page as Markdown by appending `.md` to its URL or sending `Accept: text/markdown`.

For Search and Extract, use `/v1/search` and `/v1/extract` for all new integrations and agent tool calls. Use `/v1beta/search` and `/v1beta/extract` only when maintaining an existing integration that already uses them. The request bodies changed too: on `/v1/extract`, `full_content`, `fetch_policy` and `excerpt_settings` go inside `advanced_settings`, and sending the v1beta top-level `excerpts`, `full_content` and `fetch_policy` to `/v1/extract` returns a 422. On `/v1/search`, `search_queries` is required (at least one short keyword query), and `max_results`, `source_policy` and `fetch_policy` go inside `advanced_settings`; sending only `objective`, or sending those fields at the top level, returns a 422. Do not substitute `/v1` for the documented FindAll or Ingest endpoint paths.

If you are evaluating Parallel Search or comparing it with other search APIs, read [How to Eval Parallel Search](https://docs.parallel.ai/search/evaluating-search.md) before you build the harness, especially its [Common pitfalls](https://docs.parallel.ai/search/evaluating-search.md#common-pitfalls) section. The most common mistake is sending the raw question as both `objective` and the only entry in `search_queries`. Write a goal-style `objective` and 1-3 short keyword queries instead.

The **Shopping API** takes keyword queries for products and returns products to buy.
Each result links to a store's product page and includes the product's title, store, brand,
price in the market's currency, rating, condition, availability and an image.

Use the Shopping API when an agent or application needs products a shopper can buy: finding a
specific model, comparing products in a category, or checking prices within a budget.

## 1. Set Up Prerequisites

Generate your API key on [Platform](https://platform.parallel.ai), then export it:

```bash theme={"system"}
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```

The Python example below uses `requests` (`pip install requests`).

## 2. Make Your First Shopping API Request

### Sample Request

```bash cURL theme={"system"}
curl https://api.parallel.ai/v1/shopping/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "search_queries": ["Sony WH-1000XM5"],
    "advanced_settings": {"location": "us", "max_results": 10}
  }'
```

```python Python theme={"system"}
import os

import requests

response = requests.post(
    "https://api.parallel.ai/v1/shopping/search",
    headers={"x-api-key": os.environ["PARALLEL_API_KEY"]},
    json={
        "search_queries": ["Sony WH-1000XM5"],
        "advanced_settings": {"location": "us", "max_results": 10},
    },
    timeout=60,
)
response.raise_for_status()

for result in response.json()["results"]:
    price = f"{result['price']} {result['currency']}" if "price" in result else "no price"
    print(f"{result['title']} at {result.get('merchant', 'unknown store')}: {price}")
    print(f"  buy at {result['url']}")
```

```typescript TypeScript theme={"system"}
async function main() {
    const response = await fetch("https://api.parallel.ai/v1/shopping/search", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": process.env.PARALLEL_API_KEY!,
        },
        body: JSON.stringify({
            search_queries: ["Sony WH-1000XM5"],
            advanced_settings: { location: "us", max_results: 10 },
        }),
    });
    if (!response.ok) {
        throw new Error(`Shopping API request failed: ${response.status} ${await response.text()}`);
    }

    const { results } = await response.json();
    for (const result of results) {
        const price = result.price !== undefined ? `${result.price} ${result.currency}` : "no price";
        console.log(`${result.title} at ${result.merchant ?? "unknown store"}: ${price}`);
        console.log(`  buy at ${result.url}`);
    }
}

main().catch(console.error);
```

Each request fetches live listings from many stores.

### Sample Response

The API returns a JSON response with the following structure. The `results` array below is
shortened to one product. Fields that are not known for a product, such as its availability,
are left out.

```json theme={"system"}
{
  "search_id": "search_e69f9d8eaff965b2cce81103bf2b933e",
  "session_id": "session_e69f9d8eaff965b2cce81103bf2b933e",
  "results": [
    {
      "url": "https://www.thetedstore.com/products/sony-wh-1000xm5blk-us",
      "title": "Sony WH-1000XM5 Noise-Canceling Wireless Over-Ear Headphones (Black)",
      "merchant": "thetedstore.com",
      "brand": "Sony",
      "price": 270.99,
      "currency": "USD",
      "rating": 4.7,
      "review_count": 16,
      "image_url": "https://www.thetedstore.com/cdn/shop/files/c7283550-9438-464e-a592-caac1156bb49.jpg?v=1719414314&width=1920",
      "condition": "new",
      "availability": "in_stock",
      "offers": []
    }
  ],
  "usage": [
    {
      "name": "sku_search",
      "count": 1
    }
  ]
}
```

See [Response](https://docs.parallel.ai/shopping-search/best-practices.md#response) for how to read each field.

## 3. Filter by Price and Market

Add `"max_price": 250` to the request to return only products priced at most 250 US dollars.
Results are new by default; set `"condition": "used"`, `"refurbished"` or `"any"` to change that.
Set `"advanced_settings": {"location": "gb"}` to search UK stores, with prices in pounds. See
[Best Practices](https://docs.parallel.ai/shopping-search/best-practices.md) for every request field.

## Next Steps

* **[Best Practices](https://docs.parallel.ai/shopping-search/best-practices.md)**: every request field, with examples
* **[Pricing](https://docs.parallel.ai/getting-started/pricing.md#shopping-api)**: per-request cost
* **[Rate Limits](https://docs.parallel.ai/getting-started/rate-limits.md)**: default quotas per product
