> ## 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 Best Practices

> Request fields and search guidance for 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.

Send the Shopping API one or more keyword queries for the products you want. The API
returns products to buy, each linked to a store's product page, with its price in the
market's currency.

## Request Fields

Send requests to `POST https://api.parallel.ai/v1/shopping/search` with your API key in the
`x-api-key` header. `search_queries` is required; all other fields are optional. The API
rejects unknown fields with a 422.

| Field | Type | Notes | Example |
| - | - | - | - |
| search\_queries | string\[] | One to five keyword queries, each at most 200 characters. At least one query must be non-empty. | `["Sony WH-1000XM5"]` |
| objective | string | A natural language description of the products you want. Used with `search_queries` to rank results. At most 5000 characters. | `"Over-ear headphones for long flights"` |
| advanced\_settings.location | string | ISO 3166-1 alpha-2 country of the shopper's market. Sets the stores searched and the currency of prices. Defaults to `us`. See [Markets](#markets). | `"gb"` |
| min\_price | number | Only products priced at least this, in the market's currency. | `100` |
| max\_price | number | Only products priced at most this, in the market's currency. Must be greater than 0 and not less than `min_price`. | `300` |
| condition | string | `new`, `used`, `refurbished` or `any`. Defaults to `new`. Leaves out products known to be in another condition; products with no stated condition are kept. `any` turns the filter off. | `"used"` |
| advanced\_settings.max\_results | int | Maximum number of results to return, from 1 to 40. Defaults to 20. A search can return fewer when fewer products match. Values above 40 are reduced to 40 with a warning. | `40` |
| client\_model | string | The model that creates the request and consumes the results. | `"claude-opus-5"` |
| session\_id | string | A string that groups related calls for one task. Up to 1000 characters. The API returns the value you provide, or generates one when you omit it. | `"session_<uuid>"` |

### Example

```json theme={"system"}
{
  "search_queries": ["burr coffee grinder", "conical burr grinder electric"],
  "objective": "An electric burr grinder for drip and pour-over coffee at home",
  "max_price": 80,
  "advanced_settings": {"location": "us", "max_results": 40}
}
```

## Response

Each result is one product at one store:

* `url`: the store's product page, where the product can be bought. Never a search page or a
  price-comparison page.
* `title`, `merchant` and `brand`: the product's name, the store's name, and the brand when
  known.
* `description`: what the product is and its main specifications, when one is available.
* `price` and `currency`: the price at the store when the API retrieved it, with its ISO 4217
  currency code. `original_price` is set when the product is on sale.
* `rating` and `review_count`: the average rating out of 5 and the number of reviews behind it.
* `image_url`: a product image, when one is available.
* `condition`: `new`, `used` or `refurbished`, when known.
* `availability`: `in_stock`, `out_of_stock` or `preorder`, when known.
* `offers`: other stores' pages for the same product, each with its own `url`, `merchant`,
  `price` and `currency`, when known.

Results are ordered by decreasing relevance. The API omits a field it does not know.

## Markets

`advanced_settings.location` sets the stores searched and the currency of `price`, `min_price` and `max_price`.
The API serves these markets:

`us`, `ca`, `mx`, `br`, `ar`, `cl`, `co`, `gb`, `ie`, `de`, `at`, `fr`, `be`, `nl`, `es`,
`pt`, `it`, `fi`, `gr`, `ch`, `se`, `no`, `dk`, `pl`, `cz`, `hu`, `ro`, `tr`, `il`, `ae`,
`sa`, `za`, `in`, `jp`, `kr`, `cn`, `tw`, `hk`, `sg`, `my`, `th`, `id`, `ph`, `vn`, `au`
and `nz`.

For any other valid country code, the API searches the `us` market and returns a warning.
The API ignores an invalid code, also with a warning.

## Searching Well

* **Write queries the way a shopper types them.** A model name finds that product
  (`"Samsung 990 Pro 2TB"`). A product type with its key attributes finds a category
  (`"waterproof hiking boots women"`). Leave out words such as "buy", "best" or "cheap".
* **Put one product in each query.** To compare products, or to cover other names for one
  product, send several queries in one request, up to five.
* **Put the shopper's intent in `objective`.** Describe the use, the must-haves and what to
  avoid, such as `"for a small apartment, quiet, no accessories"`. The API ranks results
  against it.
* **Filter on price with `min_price` and `max_price`, not in the query.** Words such as
  "under \$50" in a query do not filter results. The price filters do, and every result you
  get back meets them. Products without a known price are left out when you set either one.
* **Set `condition` for used or refurbished products.** Results are new by default. Most
  stores do not state a condition, so products without one are kept. For `used` or
  `refurbished`, also say it in the query, such as `"used Sony WH-1000XM5"`.
* **Set `advanced_settings.location` to the shopper's country.** It changes the stores and the currency. Write
  queries in that market's language for the best results.
* **Check the store's page before buying.** Prices and stock change often. Treat `price` and
  `availability` as the values at search time, and send the shopper to `url` to confirm them.
