# Amazon Products 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 Details Request

Returns the full 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 |
| sellerId | string | no | Specify the seller ID to query a specific offer (`m=` or `smid=` parameter in the Amazon's URL). Example: `A6T89FGPU3U0Q` is the Seller ID for Amazon `ES`. (Default: `Empty string`)
| topReviews | boolean | no | Set to false to not include the top_reviews field in the response. This will decrease the response size. (Default: `true`)

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

## Products Summary Request

Get the bulk summary data for up to 20 ASINS per request. The object returned is a [Summary Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ#Summary-Object) (the same as a Search Object but without pagination).

Important Notes:
* if the ASIN specified is Out of Stock it will not be returned in the response;
* if the ASIN is a variation of a product, the Parent ASIN will be returned;
* the results will be unordered

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

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | Marketplace country |
| asins | string | yes | ASINs list separated by `,` |

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

## Product 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`) |
| usedonly | boolean | no | Return only used offers (Default: `false`) |

**Note:** `newonly` and `usedonly` parameters cannot be true at the same time!

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

## Deals Request

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

➡️ **Method:** `GET`
🔗 **Endpoint:** `/deals`
🧩 **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`

## 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. |
| categoryId | number | no | Filters the Amazon Search by the Category ID (can be found using the Categories Endpoint) |
| page | integer | no | The page number (Default: `1` - First page) |

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

## Scrape 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`

## Rankings Endpoints

Get the top ranking products for a given Amazon Category ID.

➡️ **Method:** `GET`
🔗 **Endpoint(s):**
* **New Releases:** get the Newly Released products for the specified Category
🔗 **Endpoint:** `/new-releases`
* **Most Gifted:** get the Most Gifted products for the specified Category
🔗 **Endpoint:** `/most-gifted`
* **Most Wished:** get the Most Wished products for the specified Category
🔗 **Endpoint:** `/most-wished`
* **Bestseller:** get the Bestseller products for the specified Category
🔗 **Endpoint:** `/bestseller`
* **Movers and Shakers:** get the Top increasing selling products of the moment for the specified Category
🔗 **Endpoint:** `/movers-and-shakers`

🧩 **Params:**

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | The Marketplace where to do the Search |
| categoryId | number | yes | The Amazon Category ID where to get products from (can be found using the Categories Endpoint) |

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

## Full Categories List
Fetch all the categories for a specific country.

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

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | Marketplace country |

🔦 Response: [Full Categories List Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ?both#Full-Categories-List-Object)
❌ Errors: `400`, `500`

## Category Info
Get the `Category Info Object` from a specified Amazon Category ID.

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

| Name | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| country | string | yes | Marketplace country |
| id | number | yes | The Amazon Category ID |

🔦 Response: [Category Info Object](https://hackmd.io/fhWhj_RETOuBowVcODKJKQ?both#Category-Info-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",
    "category_id": 123456,
    "sub_categories_ids": [
        1234567,
        1234568,
        1234569
    ],
    "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"
}

## Summary Object
* Each item in the `results` array is a `Search Item Object`.

{
    "error": false,
    "results": [
        {
            Search Item Object
        },
        {
            Search Item Object
        }
    ]
}

## 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,
    "amazon_choice": false,
    "out_of_stock": false
}

## ASIN Object

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

## Ranking Object
* Each item in the `results` array is a `Ranking Item Object`.
* At the moment paging is not yet supported, so `next_page` will always be equal to `current_page`

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

## Ranking Item Object

{
    "rank": 1,
    "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,
        "currency": "$"
    },
    "reviews": {
        "total_reviews": 4173,
        "stars": 4.8
    },
    "out_of_stock": false
}

## Full Categories List Object

{
    "error": false,
    "root": [
        {
            // Category Object where "children" is an array of Category Objects
        },
        {
            // Category Object where "children" is an array of Category Objects
        }      
    ]
       
}

## Category Info Object

{
    "error": false,
    "category": {
        // Category Object
    }
}

## Category Object

{
    "id": 172659,
    "parent_id": 1266092011,
    "name": "Televisions",
    "contextFreeName": "Televisions",
    "currentLevel": 2,
    "productsCount": 22096,
    "children": [
        6459737011,
        21489946011,
        6463520011
    ]
}

## 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 products found |
| 500 | Server Error |

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