# Toppreise — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and compare product prices across Swiss retailers on Toppreise.ch, view detailed specifications, track price history, and discover the best shops for any item. Find exactly what you're looking for with comprehensive product details and real-time pricing information.

**Category:** E-commerce | **Website:** [toppreise.ch/](https://toppreise.ch/) | **Docs:** [parse.bot/marketplace/9468cee6-bce4-424f-bb58-e53b2f6bfdb6/toppreise-ch-api](https://parse.bot/marketplace/9468cee6-bce4-424f-bb58-e53b2f6bfdb6/toppreise-ch-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-toppreise-ch-api-9468cee6/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_price_history

Get historical price data for a product over the last year. Returns two arrays of [timestamp_ms, price_chf] pairs representing shipping price and pickup price time series.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | Yes | Numeric product ID (e.g. '779724') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-toppreise-ch-api-9468cee6/get_price_history \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>"}'
```

### get_product_details

Get detailed information and retailer offers for a specific product. Provide either a product_id or a full product_url. Returns the product name, canonical URL, and a list of offers from different retailers with prices and availability.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | No | Numeric product ID (e.g. '818737'). Either product_id or product_url must be provided. |
| `product_url` | string | No | Full product URL from Toppreise.ch (e.g. 'https://www.toppreise.ch/preisvergleich/Smartphones/APPLE-iPhone-17-256GB-Schwarz-MG6J4QL-A-p818737'). Either product_id or product_url must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-toppreise-ch-api-9468cee6/get_product_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>","product_url":"<string>"}'
```

### get_product_specs

Retrieve the technical datasheet/specifications for a product. Provide either a product_id or a full product_url. Returns key-value pairs of specifications such as brand, dimensions, display type, and connectivity.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_id` | string | No | Numeric product ID (e.g. '818737'). Either product_id or product_url must be provided. |
| `product_url` | string | No | Full product URL from Toppreise.ch. Either product_id or product_url must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-toppreise-ch-api-9468cee6/get_product_specs \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"<string>","product_url":"<string>"}'
```

### get_shop_details

Get detailed information about a specific shop on Toppreise.ch, including its name, address, contact info, and rating. Provide either a shop_id or a shop_url.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `shop_id` | string | No | Numeric shop ID (e.g. '150'). Either shop_id or shop_url must be provided. |
| `shop_url` | string | No | Full shop URL from Toppreise.ch (e.g. 'https://www.toppreise.ch/shops/Amazon-de-s150'). Either shop_id or shop_url must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-toppreise-ch-api-9468cee6/get_shop_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shop_id":"<string>","shop_url":"<string>"}'
```

### list_shops

List all registered shops/retailers on Toppreise.ch. Returns shop names, IDs, and URLs. No input parameters required.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-toppreise-ch-api-9468cee6/list_shops \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_products

Search for products by keyword on Toppreise.ch with optional pagination. Returns a list of matching products with names, URLs, and starting prices. Results are paginated with 0-indexed page numbers.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (0-indexed) |
| `query` | string | Yes | Search keyword (e.g. 'iPhone', 'Samsung Galaxy', 'laptop') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-toppreise-ch-api-9468cee6/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```