# toppreise.ch API — Swiss price comparison: search, every shop's CHF price with shipping, product specs, price history

> Keyword or category search on toppreise.ch (Switzerland, CHF). Rows are catalogue products (lowest price, lowest price incl. shipping, number of offers, availability) and product series (`row_type: series`, a model line with its variants nested). Filter by brand, shop and availability (ids from the `filters` action), sort by price, name, availability or popularity, 24 rows per page. Give `query`, `category_id` or both.
> ReefAPI engine `toppreise` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/toppreise/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/toppreise/v1/search — 3 credits
Keyword or category search on toppreise.ch (Switzerland, CHF). Rows are catalogue products (lowest price, lowest price incl. shipping, number of offers, availability) and product series (`row_type: series`, a model line with its variants nested). Filter by brand, shop and availability (ids from the `filters` action), sort by price, name, availability or popularity, 24 rows per page. Give `query`, `category_id` or both.

**Parameters:**
- `query` (string, optional) — Search words. Required unless category_id is given.
- `category_id` (string, optional) — toppreise category id (the number after '-c' in a category URL, e.g. …/Vollautomaten-c675 → 675, or `category_id` of a product). With query: the search inside that category. Required unless query is given.
- `brand_id` (string, optional) — Brand (manufacturer) id from the `filters` action (`brands[].id`). One id per call. An id the site does not know for this search is refused (INVALID_PARAM), never silently ignored.
- `shop_id` (string, optional) — Shop id from the `filters` action (`shops[].id`) or an offer's `shop_id`: only products this shop sells. One id per call.
- `availability` (enum, optional) — Only products with at least one offer deliverable this fast. [one of: in_stock, 1_week, 2_weeks, 4_weeks]
- `sort` (enum, optional, default "popularity") — Result order. The site groups product series only in the popularity order, so the hit count differs between orders (measured 1 117 vs 1 248). [one of: popularity, price_asc, price_desc, name_asc, name_desc, availability]
- `page` (integer, optional, default 1) — Result page, 24 top-level rows per page; the site's own pagination ends at page 100.

**Returns:** {rows:[{row_type:'product', product_id, title, url, image, offer_count, price_min, price_min_incl_shipping, best_availability_code, best_availability} | {row_type:'series', series_id, title, brand, features, url, price_min_incl_shipping, variants:[product rows]}], total, total_capped, page, last_page, has_more, sort, filters_applied}

**Example request body:**
```json
{
  "query": "kaffeevollautomat"
}
```

### POST https://api.reefapi.com/toppreise/v1/filters — 2 credits
The filter facets toppreise offers for a search: brands, shops, product series and sub-categories with their ids and hit counts, the price steps and the exact hit count. Use the ids as `brand_id` / `shop_id` / `category_id` in `search`.

**Parameters:**
- `query` (string, required) — Search words.

**Returns:** {total, brands:[{id,name}], shops:[{id,name}], series:[{id,name,brand}], categories:[{id,name,count,parent_id}], price_steps_chf:[{from,to}]}

**Example request body:**
```json
{
  "query": "kaffeevollautomat"
}
```

### POST https://api.reefapi.com/toppreise/v1/product — 3 credits
One toppreise product: title, brand, GTIN/EAN codes, manufacturer part numbers, description, category path and id, series id, lowest and highest offer price (CHF), number of offers, spec sheet, and the first page of shop offers (up to 24, lowest total first) with used offers apart.

**Parameters:**
- `product_id` (string, required) — toppreise product id: the number after '-p' in a product URL (…/DELONGHI-ECAM220-60-B-Magnifica-Start-p749259 → 749259), or `product_id` of a search row. A full product URL is accepted too.

**Returns:** {product_id, title, brand, gtins[], mpns[], description, category_path[], category_id, series_id, price_min, price_max, offer_count, specs[{name,value}], offers[...], used_offers[...]}

**Example request body:**
```json
{
  "product_id": "749259"
}
```

### POST https://api.reefapi.com/toppreise/v1/offers — 3 credits
Every shop's offer for one product (up to 96, ordered by toppreise's lowest total first): shop and shop id, offer title, price, shipping, total price incl. shipping for the cheapest payment method, the difference when discounts or fees apply, availability, shop rating and rating count, payment methods, cheapest-price badges. Used ('Occasion') offers are returned apart in `used_offers` with their condition.

**Parameters:**
- `product_id` (string, required) — toppreise product id: the number after '-p' in a product URL (…/DELONGHI-ECAM220-60-B-Magnifica-Start-p749259 → 749259), or `product_id` of a search row. A full product URL is accepted too.

**Returns:** {product_id, title, offer_count, offers:[{offer_id, position, shop_id, shop, offer_title, price, shipping, total_price, price_difference, total_has_adjustment, availability_code, availability, shop_rating, shop_rating_count, is_lowest_price, is_lowest_total, payment_methods[]}], used_offers:[... + condition]}

**Example request body:**
```json
{
  "product_id": "749259"
}
```

### POST https://api.reefapi.com/toppreise/v1/price_history — 3 credits
toppreise's own daily price history for one product: the lowest item price and the lowest price incl. shipping per day (measured: since 2023-11 on a 2023 product), with the chart's own current, lowest and highest price.

**Parameters:**
- `product_id` (string, required) — toppreise product id: the number after '-p' in a product URL (…/DELONGHI-ECAM220-60-B-Magnifica-Start-p749259 → 749259), or `product_id` of a search row. A full product URL is accepted too.
- `time_range` (enum, optional, default "1y") — How far back. [one of: 1m, 3m, 6m, 1y, all]

**Returns:** {product_id, title, points:[{date, price, price_incl_shipping}], current, lowest, highest, identity_checks}

**Example request body:**
```json
{
  "product_id": "749259",
  "time_range": "6m"
}
```

### POST https://api.reefapi.com/toppreise/v1/series — 3 credits
One toppreise product series (model line): its name and every variant product with lowest price, number of offers and availability.

**Parameters:**
- `series_id` (string, required) — Series id: `series_id` of a search row or the number after '-pc-s' in a series URL.

**Returns:** {series_id, title, total, variants:[product rows]}

**Example request body:**
```json
{
  "series_id": "64949"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=toppreise
- Human docs page: https://reefapi.com/docs/toppreise
- Overview page: https://reefapi.com/toppreise-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt