# Amazon Products / Offers / Search API

# Table of Contents
[ToC]

# How to make requests

**Base URL:** `https://amazon-products1.p.rapidapi.com/`

Follow Rapid API instructions to authenticate your request using the `x-rapidapi-host` and `x-rapidapi-key` headers.

The recommended timeout for each request is: **20 seconds**

You can find some code examples in the API Playground: https://rapidapi.com/ZombieBest/api/amazon-products1

# Supported countries

Some requests require the `country` parameter, which represents the Amazon marketplace to query.

The supported strings are:
* `US` (Amazon.com)
* `CA` (Amazon.ca)
* `UK` (Amazon.co.uk)
* `ES` (Amazon.es)
* `FR` (Amazon.fr)
* `DE` (Amazon.de)
* `IT` (Amazon.it)
* `IN` (Amazon.in)
* `AE` (Amazon.ae)
* `AU` (Amazon.com.au)
* `BR` (Amazon.com.br)
* `MX` (Amazon.com.mx)
* `TR` (Amazon.com.tr)
* `JP` (Amazon.jp)
* `CN` (Amazon.cn)
* `NL` (Amazon.nl)
* `SE` (Amazon.se)
* `SA` (Amazon.sa)
* `SG` (Amazon.sg)

# API Endpoints

## Product Detail

Returns the Product informations for the specified Marketplace and ASIN.

➡️ **Method:** `GET`
🔗 **Endpoint:** `/product`
🧩 **Params:**

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | Marketplace country |
| asin | string | yes | Product ASIN |

🔦 Response: [Product Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ#Product-Object)
❌ Errors: `400`, `405`, `500`

## Get Offers

Returns the list of Deals informations for the specified Marketplace and ASIN.

➡️ **Method:** `GET`
🔗 **Endpoint:** `/offers`
🧩 **Params:**

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | Marketplace country |
| min_number | integer | yes | The minimum amount of offers that needs to be found for the request to be accepted (and to be paid) |
| type | string | no | The offers type (Default: all) |
| max_number | integer | no | The amount of offers to retrieve (Default: 100 - Max. 1000) |
| categories | string | no | List of category names separated by `;`. These should be written exactly as on the Amazon page, but without spaces. You can also specify Category IDs. Should be URL-Encoded. |
| sub_categories | string | no | List of sub-category in the same format as the categories. |

📝 **`type` Param Description:**
The type of offers you would like to get.
Possible types are:
* `ALL` (Get all the offers)
* `LIGHTNING_DEAL` (Get only Lightning Deals)
* `DEAL_OF_THE_DAY` (Get only Deal's of the Day)
* `BEST_DEAL` (Get only Best Deals category)

🔦 Response: [Offers Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ#Offers-Object)
❌ Errors: `400`, `417`, `500`

## Listing Request

Returns the list of available offers for the specified product (New, Used, etc...).

➡️ **Method:** `GET`
🔗 **Endpoint:** `/listing`
🧩 **Params:**

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | Marketplace country |
| asin | string | yes | Product ASIN |
| page | integer | no | The page number (Default: 1 - First page) |
| primeonly | boolean | no | Only prime offers (Default: false) |
| newonly | boolean | no | Return only new offers (Default: false) |

🔦 Response: [Listing Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ#Listing-Object)
❌ Errors: `400`, `405`, `500`

## Search Request

Search for a specific query on the Amazon Marketplace.

➡️ **Method:** `GET`
🔗 **Endpoint:** `/search`
🧩 **Params:**

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | Marketplace country |
| query | string | yes | The text to search. Should be URL-Encoded. |
| page | integer | no | The page number (Default: 1 - First page) |

🔦 Response: [Search Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ#Search-Object)
❌ Errors: `400`, `500`

## Get ASIN
Returns the Product ASIN and the country from a given Amazon product URL.

➡️ **Method:** `GET`
🔗 **Endpoint:** `/asin`
🧩 **Params:**

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| url | string | yes | The URL-Encoded Amazon Product URL |

🔦 Response: [ASIN Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ#ASIN-Object)
❌ Errors: `400`, `500`

# API Objects

## Product Object
* `current_price` and `previous_price` can be `-1` if not available.

{
    "error": false,
    "asin": "B09B8W7ZK8",
    "title": "Fantastic Tees The Pledge of Allegiance T-Shirt",
    "images": [
        "https://m.media-amazon.com/images/I/51dajN9D0bL.jpg"
    ],
    "full_link": "https://www.amazon.com/dp/B09B8W7ZK8/?psc=1",
    "description": "Product Description",
    "prices": {
        "current_price":22.98,
        "previous_price":-1,
        "list_price":-1,
        "checkout_discount":-1,
        "prime_only_discount":-1,
        "currency":"$"
    },
    "reviews": {
        "total_reviews":16,
        "stars":4.1,
        "answered_questions":0,
        "top_reviews": [
            {
                Review Object
            },
            {
                Review Object
            }
        ].
    },
    "coupon": {
        "coupon_code":"",
        "coupon_discount":0,
        "box_coupon":false,
        "box_coupon_discount":0,
        "box_coupon_value":""
    },
    "prime": false,
    "amazon_choice": false,
    "out_of_stock": false,
    "deal_info": {
        "deal_id":"",
        "lightning_deal":false,
        "requested_perc":-1,
        "timestamp_end":-1
    }
    "category": "ClothingShoesJewelry",
    "sub_categories": "#NoveltyMore #Clothing #Novelty #Men #Shirts #Tshirts",
    "ship_info": {
        "sold_by":"Amazon",
        "shipped_by":"Amazon",
        "return_policy":"",
        "warranty_policy":""
    },
    "brand": "Tees Store",
    "bestseller_ranks": [
        "#175 in Clothing"
    ],
    "features":[
        "100% Cotton",
        "Machine Wash",
        "Machine washable",
        "100% Cotton. Design and screen printed from the Good Old USA.",
        "Fastastic Tees Exclusive",
        "Short sleeve. Men sizes small - 5XL"
    ],
    "variations": [
        {
            Variation / Size Object
        },
        {
            Variation / Size Object
        }
    ],
    "colors": [
        {
            Color Object
        },
        {
            Color Object
        }
    ]
}

### Review Object

{
    "username": "David",
    "avatar_link": "https://images-na.ssl-images-amazon.com/images/G/01/x-locale/common/grey-pixel.gif",
    "stars": 1,
    "title": "Cheap",
    "date": "Reviewed in the United States on August 9, 2021",
    "pattern":"Color: Maroon | Size: XX-Large",
    "verified_purchase":true,
    "text":"This shirt is made out of cheap material you got to Gildan which is a cheap brand never fits right also all the stuff on the front American flag and all the words came off in the wash I would advise don't buy this product it's cheaply made Read more",
    "positive_votes": 4,
    "images": [
        "Review Picture Image 1 Link",
        "Review Picture Image 2 Link"
    ]
}

## Color / Variation Object

{
    "description": "Color / Variation / Size Description",
    "asin":"B09B9M4V5P"
}

## Offers Object
* Each item in the `offers` array is a `Product Object`.

{
    "error": false,
    "offers": [
        {
            Product Object
        },
        {
            Product Object
        }
    ]
}

## Listing Object
* Each item in the `results` array is a `Listing Item Object`.
* `next_page` will be `null` when there are no more pages.
* `results` can be an empty array if no result was found for the specified page.

{
    "error": false,
    "current_page": 1,
    "next_page": 2,
    "title": "Raspberry Pi 4 Model B 2019 Quad Core 64 Bit WiFi Bluetooth (4GB)",
    "results": [
        {
            Listing Item Object
        },
        {
            Listing Item Object
        }
    ]
}

### Listing Item Object

{
    "current_price": 96.5,
    "seller": {
        "name": "Seller 1 Name",
        "total_reviews": 51,
        "perc_positive": 100
    },
    "shipping": {
        "price": 0,
        "from": "Amazon.com",
        "info": "Extra shipping info"
    },
    "condition": "Used - Like New",
    "comment": "Without original box"
}

## Search Object
* Each item in the `results` array is a `Search Item Object`.
* `next_page` will be `null` when there are no more pages.
* `results` can be an empty array if no result was found for the specified page.

{
    "error": false,
    "current_page": 1,
    "next_page": 2,
    "results": [
        {
            Search Item Object
        },
        {
            Search Item Object
        }
    ]
}

### Search Item Object

{
    "asin": "B08N5LLDSG",
    "title": "2020 Apple MacBook Pro with Apple M1 Chip (13-inch, 8GB RAM, 256GB SSD Storage) - Silver",
    "image": "https://m.media-amazon.com/images/I/71gD8WdSlaL._AC_UY218_.jpg",
    "full_link": "https://www.amazon.com/dp/B08N5LLDSG/?psc=1",
    "prices": {
        "current_price": 1149.99,
        "previous_price": 1299.0,
        "currency": "$"
    },
    "reviews": {
        "total_reviews": 4173,
        "stars": 4.8
    },
    "prime": true,
    "sponsored": true
}

## ASIN Object

{
    "error": false,
    "asin": "B077ZGRY9V",
    "country": "US"
}

## Error Object

{
    "error": true,
    "message": "Error description"
}

# Error Management

In case of an error the API will respond with an error code associated with an Error Object in the response.

Here's the list of the possible HTTP codes associated with errors:

| HTTP Code | Error Description |
| -------- | -------- |
| 200 | ASIN not found (404)** |
| 400 | Invalid Request |
| 404 | Invalid Endpoint |
| 405 | Invalid ASIN Format |
| 417 | Not enough offers found |
| 500 | Server Error |

**the ASIN not found (404) error will return `Status Code 200` with an Error Object inside the response.