kwery normalizes every marketplace into a consistent result shape, while preserving the fields that are specific to each one. This section documents what you get per source.
kwery covers 12 sources. The source column is the exact value to send in the request body — short identifiers, not display names (google, not google_shopping). Anything else is answered with { "error": true, "message": "unknown source: …" }.
source | Marketplace | Keys | Topics | Countries |
|---|---|---|---|---|
amazon | Amazon | term, asin, gtin | search, search_and_offers | us ca mx br uk de at ch fr it es nl be pl se jp in sg ae au tr |
google | Google Shopping | term, id, product | search | us uk de fr it es nl be at ch … (~50, see page) |
ebay | eBay | term, id, gtin | search | us uk de at fr it es au ca … |
idealo | Idealo | term, id, gtin, pzn | search | de at uk fr it es |
kaufland | Kaufland | term, id, gtin | search, search_and_offers | de cz sk pl at fr it |
otto | Otto | term, id | search | de |
billiger | Billiger | term, id, gtin | search, search_and_offers | de |
guenstiger | Guenstiger | term, id, gtin | search, search_and_offers | de |
lidl | Lidl | term, id, gtin | search, product | de at ch uk ie fr es it pl … (31) |
walmart | Walmart | term, id, gtin | search, product | us |
rakuten | Rakuten | gtin, term, id | search | jp |
aliexpress | AliExpress | term, id | search | us · rolling out |
Access is granted per source.country pair — see Authentication. A valid source in a country your account is not enabled for returns not subscribed to source, which is a different message from unknown source.
Each source page lists the fields in the content object of a product result. Common, cross-source fields include:
| Field | Description |
|---|---|
name | Product title. |
url | Canonical product URL on the marketplace. |
currency | ISO currency of the prices. |
price_min / price_avg / price_max | Aggregates across the gathered offers. |
offers_count | Number of seller offers gathered. |
offers | Array of seller offers (see each source for fields). |
buybox | The marketplace's buy box, where one exists — see Buy box semantics below. |
availability | On every offer, the buybox and the product: in_stock · limited · out_of_stock · preorder. Absent when the marketplace publishes no stock signal — never invented. See Availability. |
availability_text | The marketplace's own wording next to it, where it has one ("sofort lieferbar", "Nur noch 3 auf Lager"). |
rating / rating_count | Aggregate review signal, where available. |
Field names are unified across all sources: the same concept always has the same name — product_id, gtin, brand_name, rating / rating_count, image_url, and in offers[] the seller fields seller_name / seller_id / seller_url / seller_type / seller_rating / seller_rating_count, plus price, shipping, total (landed price) and currency. Search results arrive in the same offers[] array. Where a marketplace has a buy-box (Amazon, Walmart, Kaufland), it is the same buybox{} object. Value scales stay native (Amazon ratings are 0–100, most others 0–5) and are noted per source. Fields a source cannot supply are absent or null rather than invented; each source page adds its own extras under their native names — total, for instance, is on every offer whose marketplace publishes a shipping cost, and absent (never guessed) on the few that do not, such as a listing priced as a range.
buybox{} has one shape everywhere (price, currency, seller_name, seller_id, is_direct, shipping, total), but what it points at differs by marketplace, and that matters when you compare against it:
| Source | What buybox is |
|---|---|
| Amazon | The seller currently winning Amazon's buy box on the product page, as Amazon shows it. |
| Kaufland | The seller currently winning Kaufland's buy box on the product page. |
| Walmart | The lowest-priced offer we gathered, across all conditions — not the offer walmart.com displays by default. A used offer can win it, and the object carries no condition field yet. |
So buybox is "the offer the marketplace (or, on Walmart, the price sort) puts first", not "the offer that qualifies for you". For a like-for-like comparison, filter offers[] yourself: condition (new / used), is_direct (first-party vs marketplace seller), total (landed price) and trust.flagged_offers give you everything needed, and the result is deterministic on your side.
Every marketplace says "can this be bought right now" in its own vocabulary. kwery maps each to one field, availability, with four values, and keeps the original wording in availability_text where there is one. The field is absent — not null, not guessed — when a source publishes nothing.
| Source | Where it comes from | Values you will see |
|---|---|---|
| Walmart | Walmart's per-offer and per-product status | in_stock, out_of_stock, limited, preorder |
| Amazon | the product page's purchasable state | in_stock, out_of_stock |
| Idealo | the delivery indicator per offer (green / orange) | in_stock, limited; absent when idealo shows no delivery information |
| Lidl, Otto | the stock badge / state | in_stock, limited, out_of_stock, preorder |
| Billiger, Guenstiger | the shop's delivery text, classified | in_stock, limited, out_of_stock, preorder; text kept in availability_text |
| Rakuten | sold-out flag and per-SKU stock | in_stock, out_of_stock |
| AliExpress | per-SKU stock count | in_stock, out_of_stock |
| eBay, Google, Kaufland | — | absent |
Out-of-stock offers stay listed. On Walmart an offer the seller marks out of stock remains in offers[] with availability: "out_of_stock" and counts in offers_count (listed offers), but it takes no part in price_min / price_avg / price_max or the buybox, which are computed over purchasable offers only. A Walmart product whose page lists nothing purchasable is returned with offers: [] and a product-level availability: "out_of_stock".
For some sources, seller/shop names are not always present on the first page load. kwery can resolve missing seller names for you — when this option is enabled on your account, the service performs the extra lookups needed to populate seller_name (and marketplace fields) on offers, and reports how many resolutions ran in the result counters. This is an account-level option; contact us to enable it for your plan.
Sources are enabled per account. Contact us if you need access to one that isn't yet active on your account — we'll confirm coverage and the available keys for your use case.