{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Getting started","description":"Real-time price and offer data across major marketplaces."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide walks you through your first end-to-end request: submit a batch job, poll until"," ","it finishes, and download the results."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"id":"mock-server","level":2,"__idx":1},"children":["Try it first — no account needed "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every endpoint in this documentation can be exercised against a built-in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["mock server"]}," ","before you sign up: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.kwery.co/_mock/openapi"]},". It returns correctly-shaped"," ","example responses — no API key (any dummy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header passes) and no credits"," ","consumed:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://docs.kwery.co/_mock/openapi/job \\\n  -H \"Authorization: Bearer test123\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"source\":\"idealo\",\"country\":\"de\",\"key\":\"gtin\",\"values\":[\"4006381333962\"]}'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The data is static example data, not a live crawl, but the shapes match production exactly —"," ","build and test your integration end-to-end, then swap the base URL for"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.kwery.co"]}," and a real key. In the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi"},"children":["API Reference"]},", pick"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mock server"]}," in the Servers panel and all code samples switch to it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-get-an-api-key","__idx":2},"children":["1. Get an API key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sign up at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://kwery.co"},"children":["kwery.co"]},". Your organization is created with a free credit"," ","allowance, and the dashboard issues an API key — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kwy_live_…"]}," — that authenticates every data"," ","request. Manage keys (create, rotate, revoke) any time in the dashboard."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the key as a Bearer token (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer kwy_live_…"]},") or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header."," ","The examples below use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$KWERY_API_KEY"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication"]}," for details,"," ","including the legacy username/password option for accounts provisioned before self-serve."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-pick-a-source-key-and-country","__idx":3},"children":["2. Pick a source, key, and country"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["source"]}," supports a fixed set of ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["key"]}," types. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]}," determines what goes in"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["values"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Source"},"children":["Source"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Key"},"children":["Key"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Values format"},"children":["Values format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Example countries"},"children":["Example countries"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idealo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["term"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free-text search"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at uk fr it es"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idealo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Idealo product ID (numeric)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at uk fr it es"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idealo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gtin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["EAN / GTIN-13"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at uk fr it es"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idealo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pzn"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pharmacy product number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amazon"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["term"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free-text search"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at ch fr it es uk us …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amazon"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["asin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Amazon ASIN (10 chars)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at ch fr it es uk us …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amazon"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gtin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["EAN / GTIN-13"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at ch fr it es uk us …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["google"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["term"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free-text search"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at ch fr it es uk us nl be …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["google"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Google Shopping product ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at ch fr it es uk us nl be …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["google"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["product"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pipe-separated product record"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at ch fr it es uk us nl be …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ebay"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["term"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Free-text search"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at fr it es uk us au ca …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ebay"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["eBay item ID (numeric)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at fr it es uk us au ca …"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ebay"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gtin"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["EAN / GTIN-13"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["de at fr it es uk us au ca …"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Access is granted per ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.country"]}," pair. If your account is not enabled for the"," ","combination you request, the API responds with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"error\": true, \"message\": \"not subscribed to source\" }"]},". See the per-source pages under ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sources"},"children":["Sources"]}," for the exact"," ","fields each marketplace returns."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-submit-a-batch-job","__idx":4},"children":["3. Submit a batch job"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.kwery.co/job \\\n  -H \"Authorization: Bearer $KWERY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"idealo\",\n    \"country\": \"de\",\n    \"key\": \"gtin\",\n    \"values\": [\"4006381333962\", \"4719512101148\"]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The response returns immediately with a job object — results are assembled asynchronously:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": false,\n  \"job\": {\n    \"_id\": \"64f1c2d3e4b5a6c7d8e9f0a1\",\n    \"source\": \"idealo\",\n    \"country\": \"de\",\n    \"key\": \"gtin\",\n    \"topic\": \"search\",\n    \"values\": [\"4006381333962\", \"4719512101148\"],\n    \"status\": \"new\",\n    \"createdAt\": \"2026-04-03T10:00:00.000Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," first — validation failures are returned with HTTP 200 and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"error\": true"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/errors-and-limits"},"children":["Errors & limits"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-poll-until-finished","__idx":5},"children":["4. Poll until finished"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.kwery.co/job/64f1c2d3e4b5a6c7d8e9f0a1 \\\n  -H \"Authorization: Bearer $KWERY_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Poll until ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["finished"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"5-download-the-results","__idx":6},"children":["5. Download the results"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.kwery.co/job/64f1c2d3e4b5a6c7d8e9f0a1/download \\\n  -H \"Authorization: Bearer $KWERY_API_KEY\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each entry carries ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["key"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]},", an optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reason"]},", and the parsed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["content"]}," for that"," ","value. Results are retained for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["72 hours"]},". Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".csv"]}," to the download path for a CSV export."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"batch-vs-stream","__idx":7},"children":["Batch vs Stream"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Batch"]}," (this guide) — up to 1 000 values, poll then download. Simple, great for ad-hoc"," ","lookups."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Stream"]}," — up to 100 000 values, results pushed to your endpoint via signed webhooks as"," ","they complete. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/webhooks"},"children":["Webhooks"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":8},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/authentication"},"children":["Authentication"]}," — credentials and the subscription model."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/sources"},"children":["Sources"]}," — per-marketplace fields and supported keys."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/code-samples"},"children":["Code samples"]}," — Node.js and Python versions of every call here."]}]}]},"headings":[{"value":"Getting started","id":"getting-started","depth":1},{"value":"Try it first — no account needed","id":"mock-server","depth":2},{"value":"1. Get an API key","id":"1-get-an-api-key","depth":2},{"value":"2. Pick a source, key, and country","id":"2-pick-a-source-key-and-country","depth":2},{"value":"3. Submit a batch job","id":"3-submit-a-batch-job","depth":2},{"value":"4. Poll until finished","id":"4-poll-until-finished","depth":2},{"value":"5. Download the results","id":"5-download-the-results","depth":2},{"value":"Batch vs Stream","id":"batch-vs-stream","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Getting started"}},"lastModified":"2026-08-19T11:00:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/getting-started","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}