# Price Comparison API — multi-merchant offers, specs, EAN/GTIN and price history across Geizhals (Germany/Austria/Switzerland), Cimri and Akakçe (Turkey)

> keyword/EAN product search across a comparison source → product cards with lowest_price, offer_count, rating, image, comparison_url
> ReefAPI engine `price-compare` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/price-compare/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 or blocked calls are free.
- **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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /price-compare/v1/search — 2 credits
keyword/EAN product search across a comparison source → product cards with lowest_price, offer_count, rating, image, comparison_url

**Parameters:**
- `query` (string, required) — Search keyword (product name, model, or EAN/GTIN).
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]
- `page` (integer, optional, default 1) — Result page (1-based). Page forward with meta.next_page.
- `sort` (enum, optional) — Result sort order. geizhals: passed to the site 'sort' value. akakce: engine-side offer sort — 'p' price asc, '-p' price desc. [one of: p, -p, r, t]

**Returns:** results[] {product_id, title, lowest_price, offer_count, review_count, image, comparison_url, ean}, page, total, has_more, next_page

**Example request body:**
```json
{
  "query": "iphone 15"
}
```

### POST /price-compare/v1/product — 3 credits
full product detail (title, brand, EAN/GTIN, MPN, breadcrumb, images, specs, rating, lowest_price, embedded merchant offers) by product_id or url

**Parameters:**
- `product_id` (string, optional) — Product id. geizhals: the digits in -vNNN.html (family) / -aNNN.html (variant). cimri: the numeric id after the slug comma (…,2237451716) — prefer passing the full `url`. akakce: the numeric prCode (…,282674948.html, or just 282674948) — a bare prCode works (api6 needs no slug).
- `url` (string, optional) — Full product/variant URL (overrides product_id). geizhals: a *.html page. cimri: https://www.cimri.com/<slug>,<id>. akakce: https://www.akakce.com/<slug>,<id>.html. Take it from a search result's comparison_url.
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]

**Returns:** product{} — title, brand, ean, gtin, mpn, specifications[], images[], rating{}, lowest_price, price_range{low,high}, offer_count, breadcrumb[] (product_id or url required)

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

### POST /price-compare/v1/offers — 3 credits
all merchant offers for a product variant — per-merchant price, availability, delivery, merchant redirect URL (paginated; use a VARIANT id, -aNNN)

**Parameters:**
- `product_id` (string, optional) — Product id. geizhals: the digits in -vNNN.html (family) / -aNNN.html (variant). cimri: the numeric id after the slug comma (…,2237451716) — prefer passing the full `url`. akakce: the numeric prCode (…,282674948.html, or just 282674948) — a bare prCode works (api6 needs no slug).
- `url` (string, optional) — Full product/variant URL (overrides product_id). geizhals: a *.html page. cimri: https://www.cimri.com/<slug>,<id>. akakce: https://www.akakce.com/<slug>,<id>.html. Take it from a search result's comparison_url.
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]
- `page` (integer, optional, default 1) — Result page (1-based). Page forward with meta.next_page.
- `sort` (enum, optional) — Result sort order. geizhals: passed to the site 'sort' value. akakce: engine-side offer sort — 'p' price asc, '-p' price desc. [one of: p, -p, r, t]
- `merchant` (string, optional) — Filter offers to a merchant (vdName, case-insensitive substring — e.g. 'n11', 'Amazon', 'Trendyol'). akakce offers/compare only.
- `min_price` (number, optional) — Filter offers to price >= min_price (akakce offers/compare).
- `max_price` (number, optional) — Filter offers to price <= max_price (akakce offers/compare).
- `limit` (integer, optional) — Top-N: cap the returned offers after sort/filter (akakce offers/compare). Honest bare ceiling per query ≈ 15 offers (~5 product models × top-3).

**Returns:** offers[] {position, merchant, merchant_id, price, shipping_fee, total_price, currency, availability, badge, campaign, last_update, merchant_url}, product{ean,gtin,title,lowest_price}, page, has_more, next_page. akakce supports engine-side sort/merchant/min_price/max_price/limit over the offers.

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

### POST /price-compare/v1/price_history — 3 credits
price-history for a product — window + min/max observed. cimri ships a REAL 90-day daily min-price series; geizhals' raw point-series is JS-chart-only (min/max + range surfaced, honestly flagged, R15 no fabrication). akakce: not exposed (use cimri for TR history).

**Parameters:**
- `product_id` (string, optional) — Product id. geizhals: the digits in -vNNN.html (family) / -aNNN.html (variant). cimri: the numeric id after the slug comma (…,2237451716) — prefer passing the full `url`. akakce: the numeric prCode (…,282674948.html, or just 282674948) — a bare prCode works (api6 needs no slug).
- `url` (string, optional) — Full product/variant URL (overrides product_id). geizhals: a *.html page. cimri: https://www.cimri.com/<slug>,<id>. akakce: https://www.akakce.com/<slug>,<id>.html. Take it from a search result's comparison_url.
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]

**Returns:** history{} — product_id, window_days, current_pricerange, min_observed, max_observed, series[], series_available, series_note

### POST /price-compare/v1/category — 2 credits
browse a comparison-site category by its id/slug → product cards (same shape as search). geizhals-only (cimri/akakce expose search/product/offers/price_history/suggest/compare).

**Parameters:**
- `category` (string, required) — Geizhals category id or slug — the value after ?cat= (e.g. 'umtsover' for Handys, 'sm_ssd' for SSDs). Discover via the categories action.
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]
- `page` (integer, optional, default 1) — Result page (1-based). Page forward with meta.next_page.
- `sort` (enum, optional) — Result sort order. geizhals: passed to the site 'sort' value. akakce: engine-side offer sort — 'p' price asc, '-p' price desc. [one of: p, -p, r, t]

**Returns:** results[] product cards, category, page, has_more, next_page

### POST /price-compare/v1/categories — 2 credits
top-level category navigation tree of the comparison source (id, name, url)

**Parameters:**
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]

**Returns:** categories[] {id, name, url} top-level + sub categories

### POST /price-compare/v1/suggest — 2 credits
search autocomplete — product-name suggestions + the linked product_id for a partial query

**Parameters:**
- `query` (string, required) — Search keyword (product name, model, or EAN/GTIN).
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]

**Returns:** suggestions[] {title, product_id, url}

**Example request body:**
```json
{
  "query": "iphone 15"
}
```

### POST /price-compare/v1/compare — 4 credits
one-shot price-compare: resolve a query to its top product, then return that product's merchant offers + EAN/GTIN in a single call (search→offers convenience)

**Parameters:**
- `query` (string, required) — Search keyword (product name, model, or EAN/GTIN).
- `source` (enum, optional, default "geizhals") — Price-comparison site to query. 'geizhals' covers Germany, Austria, and the EU (geizhals.de / geizhals.at / geizhals.eu); 'akakce' and 'cimri' cover Turkey. All three return multi-merchant offer lists, EAN/GTIN identifiers, and current pricing. Idealo (idealo.de) is not currently available. [one of: geizhals, cimri, akakce]
- `country` (enum, optional, default "de") — Locale host. geizhals: de/at/eu (same DOM, different merchant pool). cimri/akakce are TR-only (country is ignored for them). [one of: de, at, eu, tr]
- `sort` (enum, optional) — Result sort order. geizhals: passed to the site 'sort' value. akakce: engine-side offer sort — 'p' price asc, '-p' price desc. [one of: p, -p, r, t]
- `merchant` (string, optional) — Filter offers to a merchant (vdName, case-insensitive substring — e.g. 'n11', 'Amazon', 'Trendyol'). akakce offers/compare only.
- `min_price` (number, optional) — Filter offers to price >= min_price (akakce offers/compare).
- `max_price` (number, optional) — Filter offers to price <= max_price (akakce offers/compare).
- `limit` (integer, optional) — Top-N: cap the returned offers after sort/filter (akakce offers/compare). Honest bare ceiling per query ≈ 15 offers (~5 product models × top-3).

**Returns:** product{title, ean, gtin, lowest_price}, offers[] {merchant, price, total_price, availability, merchant_url, product_id, product_title}, offer_count, product_models, comparison_url. akakce: offers span the query's ~5 product models × top-3 offers each, then engine-side sort/filter/top-N (depth_note in body).

**Example request body:**
```json
{
  "query": "iphone 15"
}
```

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