kwery API Reference (4.0)
Real-time price data across major European and global marketplaces.
New here? Start with the Guides — getting started, authentication, webhooks, and per-source field reference.
A mock server is built into this reference: send requests to https://docs.kwery.co/_mock/api-reference and get back correctly-shaped example responses — no signup, no API key (any dummy Authorization header passes), and no credits consumed. Select Mock server in the Servers panel and the code samples switch to it automatically.
curl -X POST https://docs.kwery.co/_mock/api-reference/job \
-H "Authorization: Bearer test123" \
-H "Content-Type: application/json" \
-d '{"source":"idealo","country":"de","key":"gtin","values":["4006381333962"]}'The data returned is static example data from this specification, not a live crawl — but the response shapes are exactly what production returns, so you can build and test your integration end-to-end before creating an account.
Each source supports a fixed set of key types. The key field determines what goes in values.
| Source | Key | Values format | Supported countries |
|---|---|---|---|
idealo | term | Free-text search | de at uk (gb) fr it es |
idealo | id | Idealo product ID (numeric) | de at uk (gb) fr it es |
idealo | gtin | EAN / GTIN-13 | de at uk (gb) fr it es |
idealo | pzn | Pharmacy product number | de |
amazon | term | Free-text search | us ca mx br uk (gb) de at ch es fr it jp in ae au nl se pl be sg tr |
amazon | asin | Amazon ASIN (10 chars) | us ca mx br uk (gb) de at ch es fr it jp in ae au nl se pl be sg tr |
amazon | gtin | EAN / GTIN-13 | us ca mx br uk (gb) de at ch es fr it jp in ae au nl se pl be sg tr |
google | term | Free-text search | us de uk (gb) au at br ca cz dk fr in ie it jp mx no pl nz nl ru sg za es se fi ch tr ar cl co be gr hu pt ro sk hk id il my ph sa kr tw th ua vn ae |
google | id | Google Shopping product ID | us de uk (gb) au at br ca cz dk fr in ie it jp mx no pl nz nl ru sg za es se fi ch tr ar cl co be gr hu pt ro sk hk id il my ph sa kr tw th ua vn ae |
google | product | Pipe-separated product record — see GoogleProductValue | us de uk (gb) au at br ca cz dk fr in ie it jp mx no pl nz nl ru sg za es se fi ch tr ar cl co be gr hu pt ro sk hk id il my ph sa kr tw th ua vn ae |
ebay | term | Free-text search | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |
ebay | id | eBay item ID (numeric) | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |
ebay | gtin | EAN / GTIN-13 | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |
kaufland | term | Free-text search | de cz sk pl at fr it |
kaufland | id | Kaufland product ID | de cz sk pl at fr it |
kaufland | gtin | EAN / GTIN-13 | de cz sk pl at fr it |
otto | term | Free-text search | de |
otto | id | Otto product ID | de |
billiger | term | Free-text search | de |
billiger | id | billiger.de product ID | de |
billiger | gtin | EAN / GTIN-13 | de |
guenstiger | term | Free-text search | de |
guenstiger | id | guenstiger.de product ID (numeric) | de |
guenstiger | gtin | EAN / GTIN-13 | de |
walmart | term | Free-text search | us |
walmart | id | Walmart item ID | us |
walmart | gtin | EAN / UPC / GTIN | us |
lidl | term | Free-text search | de at fr it nl pl uk … |
lidl | id | Lidl product ID | de at fr it nl pl uk … |
aliexpress | term | Free-text search | us |
aliexpress | id | AliExpress product ID | us |
rakuten | term | Free-text search | jp |
rakuten | id | Rakuten item ID | jp |
uk (gb)meansukandgbare two codes for the same UK marketplace — pass either one, it is not a separate locale. For Amazon,atandchare served from the amazon.de storefront with Austria/Switzerland localization.
Sign up at kwery.co; the dashboard issues your API key. Send it on every data-API request as either:
- Bearer —
Authorization: Bearer kwy_live_... - API key header —
x-api-key: kwy_live_...
Legacy/enterprise accounts provisioned before self-serve may still use HTTP Basic (username + password) or a Bearer JWT issued directly by us. See Authentication for details.
Access is controlled per source.country pair. A not subscribed to source error means your account is not provisioned for the requested combination.
Validation errors return HTTP 200 with "error": true. Always check the error field before consuming a response:
{ "error": true, "message": "country not supported by source" }Infrastructure errors (auth, 5xx) use standard HTTP status codes.
For large batches (up to 100 000 values), use the Stream endpoint. Results are pushed to your callback_url as they complete — no polling needed.
POST /stream— submit values with acallback_url- Results arrive at
callback_urlin batches as they complete GET /stream/{id}— optional progress check