⚡ Benchmarker Docs
← Site Console Get API key →
◆ API REFERENCE

Benchmarker API

Market-price intelligence over plain REST + JSON. Send products by EAN/GTIN/MPN, get normalized market prices with full geo drill-down and provenance, refreshed daily.

Base URL  https://api.bench.d1s.app
Format  JSON in / JSON out

Authentication

Every /v1/* request needs a bearer token in the Authorization header (except /health and /signup). Get a key from the signup endpoint or the landing page — rotate anytime in the console.

header
Authorization: Token bm_live_9f2b…4a1c

Quickstart

One call returns a full market snapshot for a product. Under a minute from key to first response.

curlcopy
curl https://api.bench.d1s.app/v1/prices/by-ean \
  -H "Authorization: Token $BM_KEY" \
  -d '{"ean":"4948570114344","display_currency":"EUR"}'

Rate limits & tariffs

Limits are set by your tariff. Responses include X-RateLimit-Remaining. Tracked-SKU quota is enforced on /v1/tracked.

Tariff
Tracked SKUs
Rate limit
Free
25
60 rpm
Light
500
120 rpm
Growth
5,000
300 rpm
Scale
100k+
custom
POST/v1/prices/by-ean

Market prices for one identifier, with geo drill-down and provenance.

Param
Type
Req
Description
ean
string
yes
Product identifier (EAN / GTIN).
display_currency
string
no
Normalized currency. Default EUR.
countries
string[]
no
Filter, e.g. ["PL","DE","CY"].
detail
string
no
Depth. Default store.
Request
curl …/v1/prices/by-ean \
 -H "Authorization: Token $BM_KEY" \
 -d '{
   "ean":"4948570114344",
   "display_currency":"EUR"
 }'
200 · Response
{ "ean":"4948570114344",
  "product":{ "title":"iiyama ProLite…",
    "brand":"iiyama",
    "category":"Computer Monitors" },
  "market":{ "currency":"EUR",
    "min":419,"max":612,"median":489,
    "offers_count":27,"countries_count":6 },
  "by_country":[ { "country":"PL",
    "currency_local":"PLN","median":471,
    "stores":8,"offers":[ { "retailer":"MediaMarkt",
      "city":"Warsaw","price_eur":471,
      "in_stock":true,"source":"extension",
      "match":{ "method":"ean","confidence":1.0 } } ] } ],
  "status":"ok","freshness":"2026-07-07T06:00:00Z" }
ⓘDuring beta, a cold product returns status:"queued" and prices populate as the market warms (refreshed daily).
POST/v1/prices/batch

Many identifiers in one call. items: array of {ean, ref?} (≤ 100) + display_currency, countries. Returns { display_currency, results:[…] } — each result mirrors by-ean with the echoed ref.

Request body
{ "items":[ {"ean":"4948570114344","ref":"IIY-4071"},
           {"ean":"8806091542733","ref":"LG-27GP"} ],
  "display_currency":"EUR" }
POST/v1/tracked

Add products to daily monitoring. items: array of {ean, mpn?, title?, countries?} (≤ 1000). Quota = your tariff's SKU limit.

200 · Response
{ "tariff":"free","added":2,"skipped_quota":0,"used":2,"quota":25 }
GET/v1/tracked

List the products you monitor.

200 · Response
{ "tracked":[ { "ean":"4948570114344","mpn":null,
     "title":null,"countries":["PL","DE"],
     "added_at":"2026-07-01T09:12:00Z" } ],
  "count":1 }
POST/v1/signup· no auth

Self-serve a free-tier key. Params: email.

200 · Response
{ "api_key":"bm_live_…","tariff":"free","quota":25 }

Errors

Errors return a machine code + human message. HTTP status carries the class.

Status
Code
Meaning
401
unauthorized
Missing or invalid token.
422
validation_error
Bad or missing params (e.g. no ean).
429
quota_exceeded
Rate limit or tracked-SKU quota hit.

MCP server

Connect Claude, Cursor, or your own agent — the model calls prices as native tools. Same auth as REST. Tools: prices_by_ean, drill_down_geo, compare_my_price, price_history.

mcp.json
{ "mcpServers":{ "benchmarker":{
  "command":"npx","args":["-y","@benchmarker/mcp"],
  "env":{ "BM_KEY":"bm_live_…" } } } }

Changelog

2026-07-07
Geo drill-down GA

City → store → offer detail with provenance on every price.

2026-06-20
/v1/prices/batch added

Up to 100 identifiers per call with echoed ref.

2026-05-30
Self-serve signup

POST /v1/signup — free key, no card.

Coming soon

On the roadmap — design in place, wiring as the backend lands.

POST /v1/products/match POST /v1/products/normalize GET /v1/history webhooks