# Amazon

Amazon product data, including the buy-box owner and — with `search_and_offers` — the full
list of seller offers.

## Supported countries 

`country` accepts: `us` `ca` `mx` `br` `uk (gb)` `de` `at` `ch` `es` `fr` `it` `jp` `cn` `in` `ae` `au` `nl` `se` `pl` `be` `sg` `tr`

`uk` and `gb` are the same UK marketplace. `at` and `ch` are served from the amazon.de
storefront with Austria/Switzerland localization.

## Keys 

| Key | Values | Description |
|  --- | --- | --- |
| `term` | Free text | Keyword search. |
| `asin` | 10-char ASIN | Direct product lookup. |
| `gtin` | EAN / GTIN-13 | Resolved to the matching ASIN, then fetched. |


## Topics 

| Topic | Description |
|  --- | --- |
| `search` (default) | Product page, including the current buy-box. |
| `search_and_offers` | Also fetches the full seller-offer list (Amazon's "all offers" view). |


## Product `content` fields 

| Field | Description |
|  --- | --- |
| `asin` | Amazon product ID. |
| `name` | Product title. |
| `url` | Product URL. |
| `brand` | Brand, where available. |
| `category` | Category info (`name`, `node_id`, `rank`). |
| `bsr` | Best-seller rank entries. |
| `parent_asin` | Parent ASIN for variation products. |
| `currency` | ISO currency. |
| `buybox_price` | Buy-box price. On a Prime-exclusive deal this is the **regular (non-Prime) price**; the Prime price is in `prime_price`. |
| `buybox_owner` / `buybox_owner_id` | Seller currently winning the buy box. |
| `seller_type` | Fulfilment of the buy-box seller: `amazon` (sold by Amazon, 1P), `fba` (third-party, Fulfilled by Amazon), `fbm` (third-party, fulfilled by merchant). |
| `is_prime` | `true` when the buy box carries a Prime-exclusive price (a discount available only to Prime members). |
| `prime_price` | The Prime-exclusive price when `is_prime` is `true`, otherwise `null`. |
| `shipping` | Buy-box shipping cost. |
| `is_available` / `availability` | Availability flags. |
| `no_shops` | Number of distinct sellers seen. |
| `on_amazon_since` | First-seen date, where available. |
| `description_text` / `bullet_text` | Product description and bullet points. |
| `review_rating` / `review_count` | Aggregate reviews. |
| `offers_count` | Number of offers (populated with `search_and_offers`). |
| `price_min` / `price_avg` / `price_max` | Offer price aggregates (with `search_and_offers`). |
| `offers` | Seller offers (with `search_and_offers`). |


With `topic: search_and_offers`, `offers[]` lists each seller offer (seller name, price,
currency, shipping, condition). The buy-box stays available separately as `buybox_*`.

## Example request 

cURL
```bash
curl -s https://api.kwery.co/job \
  -H "Authorization: Bearer $KWERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source":"amazon","country":"de","key":"asin","topic":"search_and_offers","values":["B0DGHP6V8V"]}'
```

Node.js
```js
const res = await fetch('https://api.kwery.co/job', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KWERY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ source: 'amazon', country: 'de', key: 'asin', topic: 'search_and_offers', values: ['B0DGHP6V8V'] }),
});
const data = await res.json();
if (data.error) throw new Error(data.message);
console.log('job id:', data.job._id);
```

Python
```python
import os, requests

res = requests.post(
    "https://api.kwery.co/job",
    headers={"Authorization": f"Bearer {os.environ['KWERY_API_KEY']}"},
    json={"source": "amazon", "country": "de", "key": "asin", "topic": "search_and_offers", "values": ["B0DGHP6V8V"]},
)
data = res.json()
if data.get("error"):
    raise RuntimeError(data["message"])
print("job id:", data["job"]["_id"])
```

JavaScript
```js
const res = await fetch('https://api.kwery.co/job', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${KWERY_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ source: 'amazon', country: 'de', key: 'asin', topic: 'search_and_offers', values: ['B0DGHP6V8V'] }),
});
const data = await res.json();
if (data.error) throw new Error(data.message);
console.log('job id:', data.job._id);
```

PHP
```php
<?php
$ch = curl_init('https://api.kwery.co/job');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('KWERY_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => '{"source":"amazon","country":"de","key":"asin","topic":"search_and_offers","values":["B0DGHP6V8V"]}',
]);
$data = json_decode(curl_exec($ch), true);
if ($data['error']) { throw new Exception($data['message']); }
echo 'job id: ' . $data['job']['_id'];
```

Go
```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{"source":"amazon","country":"de","key":"asin","topic":"search_and_offers","values":["B0DGHP6V8V"]}`)
	req, _ := http.NewRequest("POST", "https://api.kwery.co/job", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KWERY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
	fmt.Println("job:", data["job"])
}
```

Java
```java
var client = java.net.http.HttpClient.newHttpClient();
var request = java.net.http.HttpRequest.newBuilder()
    .uri(java.net.URI.create("https://api.kwery.co/job"))
    .header("Authorization", "Bearer " + System.getenv("KWERY_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofString(
        "{\"source\":\"amazon\",\"country\":\"de\",\"key\":\"asin\",\"topic\":\"search_and_offers\",\"values\":[\"B0DGHP6V8V\"]}"))
    .build();
var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

C#
```csharp
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization",
    $"Bearer {Environment.GetEnvironmentVariable("KWERY_API_KEY")}");
var body = new StringContent(
    """{"source":"amazon","country":"de","key":"asin","topic":"search_and_offers","values":["B0DGHP6V8V"]}""",
    System.Text.Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.kwery.co/job", body);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

Ruby
```ruby
require 'net/http'
require 'json'

uri = URI('https://api.kwery.co/job')
req = Net::HTTP::Post.new(uri, {
  'Authorization' => "Bearer #{ENV['KWERY_API_KEY']}",
  'Content-Type' => 'application/json',
})
req.body = '{"source":"amazon","country":"de","key":"asin","topic":"search_and_offers","values":["B0DGHP6V8V"]}'
data = JSON.parse(Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }.body)
raise data['message'] if data['error']
puts "job id: #{data['job']['_id']}"
```

## Example response 

Results are fetched with `GET /job/{id}/download` once the job is `finished` — each entry is the result for one input value (abridged):

```json
[
  {
    "key": "B0DGHP6V8V",
    "success": true,
    "reason": null,
    "content": {
      "asin": "B0DGHP6V8V",
      "name": "Sample Product Title",
      "url": "https://www.amazon.de/dp/B0DGHP6V8V",
      "brand": "SampleBrand",
      "currency": "EUR",
      "buybox_price": 27.99,
      "buybox_owner": "Amazon.de",
      "seller_type": "amazon",
      "is_prime": true,
      "offers_count": 2,
      "price_min": 27.99,
      "price_max": 34.99,
      "offers": [
        { "shop_name": "Amazon.de", "price": 27.99, "currency": "EUR", "shipping": 0, "condition": "new" },
        { "shop_name": "ThirdPartySeller GmbH", "price": 34.99, "currency": "EUR", "shipping": 3.99, "condition": "new" }
      ]
    }
  }
]
```