API documentation

For people writing agents that shop. One product query in, one JSON document out. No SDK required, a GET is enough.

Overview

ShoppingQuery answers one question: where can this product be bought, and for how much. You send a GTIN or a title. You get offers, prices, stock, images, content and price history from 250+ shops and marketplaces in 32 countries, in one JSON schema.

Base URL: https://shoppingquery.com (the planned public address). Examples work on any host that runs the service, including localhost.

Format: JSON over HTTPS, GET only. The stream uses Server-Sent Events. Responses carry version: "1"; field names are snake_case and stable.

Three doors:

• GTIN (exact). GET /v1/ean/{gtin}. The barcode is 8 to 14 digits. Where a source publishes a barcode, the offer is checked against it and flagged match.ean_verified.
• Title (keywords). GET /v1/title?q=. The title is searched as keywords in the selected countries. Set resolve=true to also look up GTIN candidates and, when one is confident, search by barcode.
• Stream (SSE). GET /v1/search/stream. One event per source as it answers, so the first prices arrive in about a second.

Quickstart

Offers for one barcode in GB and the US:

curl 'https://shoppingquery.com/v1/ean/4548736132580?countries=GB,US'

The answer is one JSON object: query (what you asked and how the call went), product (title, brand, images, specs), offers (cheapest first, in EUR), sources (every engine asked, matched or not), stats, timing_ms, version.

Python, with httpx:

import httpx

doc = httpx.get(
    "https://shoppingquery.com/v1/ean/4548736132580",
    params={"countries": "GB,US"},
    timeout=60.0,
).json()

print(doc["product"]["title"])
for o in doc["offers"][:5]:
    print(o["retailer"], o["price"]["amount"], o["price"]["currency"],
          o.get("availability"), o["match"]["ean_verified"])

JavaScript:

const res = await fetch(
  "https://shoppingquery.com/v1/ean/4548736132580?countries=GB,US"
);
const doc = await res.json();
console.log(doc.product?.title, doc.offers.length);

Offers

GET /v1/ean/{gtin} returns the unified document: product, buybox, every offer, every source. GET /v1/ean/{gtin}/offers returns the same offers and buybox with a little less product prose, and reports cache state per source. For the same source list the offers match.

Parameters

Offer fields

Also on an offer: title, url, url_locked, image, grade, grade_label, refurb_class, match.verification, match.reasons, listings, price_outlier.

Example

curl 'https://shoppingquery.com/v1/ean/4548736132580?countries=GB,US'

Example response (trimmed):

{
  "query": {
    "type": "ean",
    "value": "4548736132580",
    "seconds": 4.2,
    "offers_found": 3,
    "sources_queried": 14,
    "sources_used": 3
  },
  "product": {
    "gtin": "4548736132580",
    "title": "Sony WH-1000XM5 Wireless Noise Cancelling Headphones",
    "brand": "Sony",
    "image": "https://images.example.com/wh-1000xm5-black.jpg"
  },
  "offers": [
    {
      "source": "idealo.de",
      "source_type": "comparison",
      "country": "GB",
      "retailer": "amazon.co.uk",
      "shop": "Amazon",
      "price": {
        "amount": 279.00,
        "currency": "GBP",
        "amount_eur": 324.10,
        "item": 279.00,
        "shipping": 0.0,
        "total": 279.00,
        "basis": "total"
      },
      "condition": "new",
      "availability": "in_stock",
      "match": { "scope": "exact", "ean_verified": true, "verification": "ean" }
    },
    {
      "source": "bestbuy.com",
      "source_type": "retailer",
      "country": "US",
      "retailer": "bestbuy.com",
      "shop": "Best Buy",
      "price": {
        "amount": 328.00,
        "currency": "USD",
        "amount_eur": 302.40,
        "item": 328.00,
        "basis": "item"
      },
      "condition": "new",
      "availability": "limited",
      "match": { "scope": "exact", "ean_verified": true, "verification": "ean" }
    }
  ],
  "sources": [
    { "source": "idealo.de", "country": "DE", "status": "matched", "offers": 2 },
    { "source": "bestbuy.com", "country": "US", "status": "matched", "offers": 1 }
  ],
  "stats": { "sources": 2, "matched": 2, "offers": 2,
             "by_condition": { "new": 2 }, "by_scope": { "exact": 2 } },
  "timing_ms": 4210,
  "version": "1"
}

Price history

GET /v1/ean/{gtin}/price-history returns one price series per history source, plus a cross-country combined series of the lowest EUR price per day.

Parameters

Each point is one day: date (YYYY-MM-DD), lowest_price, currency. A series carries source, country, product_id, scope (variant for one colour and size, model when the source pools variants), points, and min/max/current price. Combined points add which source and country won that day.

curl 'https://shoppingquery.com/v1/ean/4548736132580/price-history?country=DE&days=30'

Example response (trimmed):

{
  "query": { "type": "ean", "value": "4548736132580" },
  "gtin": "4548736132580",
  "country": "DE",
  "days": 30,
  "histories": [
    {
      "source": "geizhals.de",
      "country": "DE",
      "product_id": "2145678",
      "scope": "variant",
      "currency": "EUR",
      "points": [
        { "date": "2026-09-15", "lowest_price": 289.00, "currency": "EUR" },
        { "date": "2026-09-16", "lowest_price": 279.00, "currency": "EUR" }
      ],
      "min_price": 279.00,
      "max_price": 289.00,
      "current_price": 279.00,
      "status": "matched"
    }
  ],
  "combined": {
    "currency": "EUR",
    "days": 2,
    "min_price": 279.00,
    "avg_price": 284.00,
    "max_price": 289.00,
    "points": [
      { "date": "2026-09-16", "price_eur": 279.00, "source": "geizhals.de",
        "country": "DE", "price": 279.00, "currency": "EUR" }
    ]
  },
  "timing_ms": 890,
  "version": "1"
}

Content

GET /v1/ean/{gtin}/content returns title, brand, description, specifications and variant attributes for one barcode. GET /v1/ean/{gtin}/content/fast returns one harmonised truth (title, thumbnail, descriptions, specs, images, retailer links) in about a second.

Use /content/fast when a human or an agent is waiting. It races the tier-1 exact sources against a hard deadline and returns the first strong answer (partial: true when the deadline fired early). Late sources fill the cache, so a repeat call answers in about 10 ms. Use /content when you want the fuller, slower pass with per-spec source lists.

Parameters

countries does not apply: content is not market-bound.

curl 'https://shoppingquery.com/v1/ean/4548736132580/content/fast?country=DE'

Example response (trimmed):

{
  "query": {
    "type": "ean",
    "value": "4548736132580",
    "seconds": 0.9,
    "sources_queried": 8,
    "sources_used": 3
  },
  "gtin": "4548736132580",
  "title": "Sony WH-1000XM5 Wireless Noise Cancelling Headphones",
  "title_scope": "variant",
  "brand": "Sony",
  "thumbnail": "https://images.example.com/wh-1000xm5-black.jpg",
  "description": "Industry-leading noise cancellation with Auto NC Optimizer.",
  "short_description": "Over-ear wireless headphones, 30 hours battery.",
  "specs": [
    { "name": "Colour", "value": "Black", "sources": ["idealo.de"] },
    { "name": "Weight", "value": "250 g", "sources": ["idealo.de", "coolblue.nl"] }
  ],
  "images_count": 4,
  "partial": false,
  "deadline_hit": false,
  "version": "1"
}

Images

GET /v1/ean/{gtin}/images returns the images of this exact variant, duplicates removed (same photo from three shops becomes one tile that lists all three). Each item is url plus the sources that show it.

Parameters: sources (override the fixed set), fresh (skip the 7 day cache). A wider second set runs only when the fast set finds no image.

curl 'https://shoppingquery.com/v1/ean/4548736132580/images'

Example response (trimmed):

{
  "query": { "type": "ean", "value": "4548736132580" },
  "gtin": "4548736132580",
  "title": "Sony WH-1000XM5 Wireless Noise Cancelling Headphones",
  "images": [
    {
      "url": "https://images.example.com/wh-1000xm5-black.jpg",
      "sources": ["idealo.de", "coolblue.nl", "mediamarkt.de"]
    }
  ],
  "version": "1"
}

Resellers

GET /v1/ean/{gtin}/resellers returns one row per retailer selling this EAN, cheapest first. Each row names the countries and sources it appeared on, its price range and conditions, and whether any listing was proven by barcode. Default match filter: exact,grouped.

Parameters as on /offers: countries, sources, cross_border, condition, match, amazon, fresh.

curl 'https://shoppingquery.com/v1/ean/4548736132580/resellers?countries=NL,DE'

Example response (trimmed):

{
  "query": { "type": "ean", "value": "4548736132580" },
  "gtin": "4548736132580",
  "title": "Sony WH-1000XM5 Wireless Noise Cancelling Headphones",
  "resellers": [
    {
      "retailer": "coolblue.nl",
      "name": "Coolblue",
      "countries": ["NL"],
      "sources": ["kieskeurig.nl", "klarna.nl"],
      "offers": 2,
      "min_eur": 279.00,
      "max_eur": 289.00,
      "conditions": ["new"],
      "ean_verified": true,
      "scope": "exact"
    },
    {
      "retailer": "mediamarkt.de",
      "name": "MediaMarkt",
      "countries": ["DE"],
      "sources": ["idealo.de"],
      "offers": 1,
      "min_eur": 299.00,
      "max_eur": 299.00,
      "conditions": ["new"],
      "ean_verified": true,
      "scope": "exact"
    }
  ],
  "version": "1"
}

Also useful

GET /v1/brand/{brand}/eans lists every GTIN our sources will prove for a brand (the full list, never sampled). Parameters: countries, sources, max_pages (default 30, cap 200), budget_s (default 20, max 300; when it runs out the document returns with partial: true), fresh.

GET /v1/countries lists the markets and engines behind them. GET /v1/retailers lists which engine surfaces which retailer. GET /v1/fx returns the ECB reference rates (units per 1 EUR) used for the EUR conversions.

Title search

GET /v1/title?q= searches a product title on the shops of the selected countries or sources and returns the same unified document. Every source runs its own title search and reports match.verification: "title", because there is no barcode to prove against. partial is true when the time budget cut a source. Nothing is sent to a barcode comparison site by default. When nothing matches, one relaxed retry drops spec words (capacity, size, colour) and says so: those offers carry match.reasons relaxed_query and are never mixed with strict matches.

Optional barcode lookup: resolve=true also asks idealo.de and geizhals.de for GTIN candidates.

1. resolve=true and auto (default true), top candidate scores 0.6 or higher: run the EAN search for that GTIN. The answer carries query.resolved_gtin and query.candidates.
2. resolve=true with candidates but no auto-resolve (auto=false, or the score is under 0.6): candidates only, offers empty. Pick one and call /v1/ean/{gtin} yourself.
3. resolve=true and no candidate: the title search above.

Parameters: q (3 to 200 characters, required), countries, sources, cross_border, condition, match, amazon, resolve, auto. The query is the raw text; quotes and operators are not interpreted.

curl 'https://shoppingquery.com/v1/title?q=Sony%20WH-1000XM5&countries=GB,US'

Example response (trimmed):

{
  "query": {
    "type": "title",
    "value": "Sony WH-1000XM5",
    "resolved_gtin": "4548736132580",
    "candidates": [
      {
        "gtin": "4548736132580",
        "title": "Sony WH-1000XM5",
        "brand": "Sony",
        "source": "title-resolve",
        "score": 0.91
      }
    ]
  },
  "product": {
    "gtin": "4548736132580",
    "title": "Sony WH-1000XM5 Wireless Noise Cancelling Headphones",
    "brand": "Sony"
  },
  "offers": [
    {
      "source": "idealo.de",
      "source_type": "comparison",
      "country": "GB",
      "retailer": "amazon.co.uk",
      "price": { "amount": 279.00, "currency": "GBP", "amount_eur": 324.10 },
      "condition": "new",
      "availability": "in_stock",
      "match": { "scope": "exact", "ean_verified": true, "verification": "ean" }
    }
  ],
  "version": "1"
}

Result groups (view and clusters)

A broad title such as doraemon returns many different products: games, plush toys, manga volumes, sneakers. One price spread over all of them means nothing, so the document groups the offers into products and says how to show them.

• view: "product": the offers are one product (a barcode or ASIN lookup, or a title resolved to a GTIN). Read product, buybox and offers as before.
• view: "serp": the offers are several products. Show clusters as a result list, and only harmonise (price spread, best offer) inside one cluster.

Any other title lookup is always "serp". top_share (0 to 1) reports the share of offers the biggest group holds; it is a hint and never changes the view.

Stream (SSE)

GET /v1/search/stream sends one Server-Sent Events frame per source the moment it answers. First prices in about a second; the rest fills in until the budget ends. Feed it a barcode or a title (or both: mode=title with an ean also runs the title search).

Parameters

Events

Title mode sends meta, result (including status: "skipped" rows for sources that only speak barcode), product, optional resolved, and done. No gallery, no amazon, no consensus.

const es = new EventSource(
  "https://shoppingquery.com/v1/search/stream?ean=4548736132580"
);
es.addEventListener("result", (e) => {
  const row = JSON.parse(e.data);
  console.log(row.site, row.offer_count, row.offers?.[0]?.price);
});
es.addEventListener("product", (e) => console.log(JSON.parse(e.data).title));
es.addEventListener("done", () => es.close());

curl -N 'https://shoppingquery.com/v1/search/stream?ean=4548736132580'

Reference

Machine readable contracts: OpenAPI schema and llms.txt.

ASIN routes resolve the ASIN to an exact EAN first, then run the matching EAN route. marketplace defaults to de. Paths: GET /v1/asin/{asin}, GET /v1/asin/{asin}/offers, GET /v1/asin/{asin}/content, GET /v1/asin/{asin}/content/fast, GET /v1/asin/{asin}/images, GET /v1/asin/{asin}/resellers, plus GET /v1/whereami and GET /health.

Errors

Every 4xx and 5xx body is one JSON object:

{ "error": "EAN must be 8 to 14 digits" }

An empty offers list is not an error. It means nothing matched; read query and sources.

Limits and credits

Demo endpoint (/v1/demo/stream, the live box on the home page): 5 searches a minute per IP, 3 streams at once, fixed sources per country (you cannot pick engines). Query 3 to 80 characters, barcode or title. Over the limit you get a 429 with a plain sentence.

API keys and billing are not open yet. There is no key to send and nothing to top up. Keys and billing open soon; tell us what you need on the contact page.

Credits per call, as on the pricing page:

A cold product search takes 4 to 60 seconds depending on the sources. Prefer the stream when latency matters. Robots and agents: llms.txt, llms-full.txt.