{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-api-reference.yaml","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"api-reference.yaml","settings":{"baseUrlPath":"/api-reference"},"disableAutoScroll":true,"seo":{"title":"kwery API Reference","siteUrl":"https://docs.kwery.co","description":"Full OpenAPI reference for the kwery Batch and Stream APIs — every endpoint, parameter, and response schema."},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"kwery API Reference","version":"4.0","description":"Real-time price data across major European and global marketplaces.\n\nNew here? Start with the **[Guides](https://docs.kwery.co/)** — getting started,\nauthentication, webhooks, and per-source field reference.\n\n## Try it — no account needed\n\nA **mock server** is built into this reference: send requests to\n`https://docs.kwery.co/_mock/api-reference` and get back correctly-shaped example\nresponses — no signup, no API key (any dummy `Authorization` header passes),\nand no credits consumed. Select **Mock server** in the Servers panel and the\ncode samples switch to it automatically.\n\n```bash\ncurl -X POST https://docs.kwery.co/_mock/api-reference/job \\\n  -H \"Authorization: Bearer test123\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"source\":\"idealo\",\"country\":\"de\",\"key\":\"gtin\",\"values\":[\"4006381333962\"]}'\n```\n\nThe data returned is static example data from this specification, not a live\ncrawl — but the response shapes are exactly what production returns, so you can\nbuild and test your integration end-to-end before creating an account.\n\n## Source and key reference\n\nEach source supports a fixed set of `key` types. The `key` field\ndetermines what goes in `values`.\n\n| Source | Key | Values format | Supported countries |\n|--------|-----|---------------|---------------------|\n| `idealo` | `term` | Free-text search | de at uk (gb) fr it es |\n| `idealo` | `id` | Idealo product ID (numeric) | de at uk (gb) fr it es |\n| `idealo` | `gtin` | EAN / GTIN-13 | de at uk (gb) fr it es |\n| `idealo` | `pzn` | Pharmacy product number | de |\n| `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 |\n| `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 |\n| `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 |\n| `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 |\n| `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 |\n| `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 |\n| `ebay` | `term` | Free-text search | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |\n| `ebay` | `id` | eBay item ID (numeric) | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |\n| `ebay` | `gtin` | EAN / GTIN-13 | au at be ca fr de ie it hk my nl pl sg es ch uk (gb) us |\n| `kaufland` | `term` | Free-text search | de cz sk pl at fr it |\n| `kaufland` | `id` | Kaufland product ID | de cz sk pl at fr it |\n| `kaufland` | `gtin` | EAN / GTIN-13 | de cz sk pl at fr it |\n| `otto` | `term` | Free-text search | de |\n| `otto` | `id` | Otto product ID | de |\n| `billiger` | `term` | Free-text search | de |\n| `billiger` | `id` | billiger.de product ID | de |\n| `billiger` | `gtin` | EAN / GTIN-13 | de |\n| `guenstiger` | `term` | Free-text search | de |\n| `guenstiger` | `id` | guenstiger.de product ID (numeric) | de |\n| `guenstiger` | `gtin` | EAN / GTIN-13 | de |\n| `walmart` | `term` | Free-text search | us |\n| `walmart` | `id` | Walmart item ID | us |\n| `walmart` | `gtin` | EAN / UPC / GTIN | us |\n| `lidl` | `term` | Free-text search | de at fr it nl pl uk … |\n| `lidl` | `id` | Lidl product ID | de at fr it nl pl uk … |\n| `aliexpress` | `term` | Free-text search | us |\n| `aliexpress` | `id` | AliExpress product ID | us |\n| `rakuten` | `term` | Free-text search | jp |\n| `rakuten` | `id` | Rakuten item ID | jp |\n\n> `uk (gb)` means `uk` and `gb` are two codes for the **same** UK marketplace —\n> pass either one, it is not a separate locale. For Amazon, `at` and `ch` are\n> served from the amazon.de storefront with Austria/Switzerland localization.\n\n## Authentication\n\nSign up at [kwery.co](https://kwery.co); the dashboard issues your API key. Send it on\nevery data-API request as either:\n- **Bearer** — `Authorization: Bearer kwy_live_...`\n- **API key header** — `x-api-key: kwy_live_...`\n\nLegacy/enterprise accounts provisioned before self-serve may still use HTTP Basic\n(username + password) or a Bearer JWT issued directly by us. See\n[Authentication](guides/authentication.md) for details.\n\nAccess is controlled per `source.country` pair. A `not subscribed to source`\nerror means your account is not provisioned for the requested combination.\n\n## Response envelope\n\nValidation errors return **HTTP 200** with `\"error\": true`. Always check the\n`error` field before consuming a response:\n\n```json\n{ \"error\": true, \"message\": \"country not supported by source\" }\n```\n\nInfrastructure errors (auth, 5xx) use standard HTTP status codes.\n\n## Stream API\n\nFor large batches (up to **100 000 values**), use the Stream endpoint.\nResults are pushed to your `callback_url` as they complete — no polling needed.\n\n1. `POST /stream` — submit values with a `callback_url`\n2. Results arrive at `callback_url` in batches as they complete\n3. `GET /stream/{id}` — optional progress check\n\n## Batch API\n\nFor standard batches (up to **1 000 values**), use the Batch endpoint.\nResults are retained for **72 hours**.\n\n1. `POST /job` — submit a list of values, receive a job ID\n2. `GET /job/{id}` — poll until `status` is `finished`\n3. `GET /job/{id}/download` — retrieve structured results\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.kwery.co","port":4000,"ipAddress":"216.73.217.31"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"main"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/api-reference","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}