# Amazon tools

Search results, products, sellers, and ranked queries.

## Search Amazon

Tool: `amazon_search_products`

Amazon's results page for a search, organic and sponsored rows in page order. Not for one product's detail (amazon_get_product), Google Shopping (shopping_search_products) or search volume (amazon_get_keyword_metrics).

Returns keyword, results_count, rows[] (rank, type organic or sponsored, asin, title, url, image_url, price, price_to, currency, rating, ratings_count, bought_past_month, is_amazon_choice, is_best_seller, offers[] badges) and related_searches[] (can be empty). Amazon reviews are not available.

Cost: 2 credits per 100 results. Default 100 = 2 credits. Cached 1 day.

Endpoint: `POST /api/amazon/tools/amazon_search_products`

Cost: 2 credits per 100 results. Default 100 = 2 credits. Cached 1 day.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "minLength": 1,
      "maxLength": 700,
      "description": "Required."
    },
    "depth": {
      "default": 100,
      "description": "Results to fetch. Default 100, max 700; billed per 100.",
      "type": "integer",
      "minimum": 1,
      "maximum": 700
    },
    "location": {
      "default": "United States",
      "description": "Location name or code; also picks the Amazon marketplace. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "keyword"
  ]
}
```

## Get an Amazon listing

Tool: `amazon_get_product`

One product's listing by ASIN. For sellers use amazon_get_sellers; for the searches it ranks for use amazon_get_keywords. Reviews are not available.

Returns asin, parent_asin, title, url, byline, price, regular_price (struck-through list price; null without a discount), discount_percent, currency, rating, ratings_count, is_amazon_choice, is_available, categories[] (broadest first), description, specs[] (group, name, value), variation_asins[], images[].

Cost: 2 credits. Cached 1 day.

Endpoint: `POST /api/amazon/tools/amazon_get_product`

Cost: 2 credits. Cached 1 day.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "asin": {
      "type": "string",
      "pattern": "^[A-Z0-9]{10}$",
      "description": "Required. The 10 characters after /dp/ in a product URL."
    },
    "location": {
      "default": "United States",
      "description": "Location name or code; also picks the Amazon marketplace. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "asin"
  ]
}
```

## Get an Amazon product's sellers

Tool: `amazon_get_sellers`

Every seller offering one product, Buy Box first. For the listing use amazon_get_product; for prices at other stores use shopping_get_sellers.

Returns asin, title, has_featured_offer (false when no seller holds the Buy Box; rows then start at rank 2) and rows[]: rank (1 holds the Buy Box), seller, seller_url (null for Amazon itself), ships_from, price, regular_price, currency, discount_percent, condition, delivery.

Cost: 2 credits. Cached 6 hours.

Endpoint: `POST /api/amazon/tools/amazon_get_sellers`

Cost: 2 credits. Cached 6 hours.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "asin": {
      "type": "string",
      "pattern": "^[A-Z0-9]{10}$",
      "description": "Required. The 10 characters after /dp/ in a product URL."
    },
    "location": {
      "default": "United States",
      "description": "Location name or code; also picks the Amazon marketplace. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "asin"
  ]
}
```

## Get an Amazon product's ranking keywords

Tool: `amazon_get_keywords`

The Amazon searches one product ranks for, highest volume first.

Returns rows[]: keyword, volume (monthly Amazon searches, a model), rank (position on the results page counting organic and sponsored rows), type (organic or sponsored), results_count.

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Endpoint: `POST /api/amazon/tools/amazon_get_keywords`

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "asin": {
      "type": "string",
      "pattern": "^[A-Z0-9]{10}$",
      "description": "Required. The 10 characters after /dp/ in a product URL."
    },
    "location": {
      "default": "United States",
      "description": "Location name or code; also picks the Amazon marketplace. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "asin"
  ]
}
```

## Find competing Amazon products

Tool: `amazon_get_competitors`

Products competing with one product for the same Amazon searches; the product itself is left out. Titles are not included: call amazon_get_product for them.

Returns rows[]: asin, shared_keywords, avg_position, organic_keywords, organic_volume, sponsored_keywords.

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Endpoint: `POST /api/amazon/tools/amazon_get_competitors`

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "asin": {
      "type": "string",
      "pattern": "^[A-Z0-9]{10}$",
      "description": "Required. The 10 characters after /dp/ in a product URL."
    },
    "location": {
      "default": "United States",
      "description": "Location name or code; also picks the Amazon marketplace. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "asin"
  ]
}
```

## Get Amazon search volume

Tool: `amazon_get_keyword_metrics`

Monthly Amazon search volume for keywords you supply. Volumes are a vendor model with no independent accuracy test, and do not share a unit with Google volumes.

Returns rows[] in the input order: keyword, volume (null = no data).

Cost: 5 + 5 per 100 keywords. 10 keywords = 6 credits. Cached 7 days.

Endpoint: `POST /api/amazon/tools/amazon_get_keyword_metrics`

Cost: 5 + 5 per 100 keywords. 10 keywords = 6 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "keywords": {
      "minItems": 1,
      "maxItems": 1000,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 200
      },
      "description": "Required. At most 1000."
    },
    "location": {
      "default": "United States",
      "description": "Location name or code; also picks the Amazon marketplace. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "keywords"
  ]
}
```

## Get Amazon keyword ideas

Tool: `amazon_search_keywords`

Amazon search ideas related to a seed keyword, with volume.

Returns rows[]: keyword, volume.

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

Endpoint: `POST /api/amazon/tools/amazon_search_keywords`

Cost: 5 + 5 per 100 rows. Default 100 rows = 10 credits. Cached 7 days.

### Input JSON schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "seed": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Required. The seed keyword."
    },
    "location": {
      "default": "United States",
      "description": "Location name or code; also picks the Amazon marketplace. Default United States.",
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      ]
    },
    "language": {
      "default": "en",
      "description": "ISO 639-1 language code. Default en.",
      "type": "string",
      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z]{2,4})?$"
    },
    "limit": {
      "default": 100,
      "description": "Max rows. Default 100, cap 1000.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "cursor": {
      "description": "The next page: meta.cursor from the previous result.",
      "type": "string"
    },
    "max_credits": {
      "description": "Refuse the call with BudgetExceeded if the estimate is higher.",
      "type": "number",
      "minimum": 0
    },
    "dry_run": {
      "default": false,
      "description": "Return only meta with the estimate. Costs nothing.",
      "type": "boolean"
    },
    "idempotency_key": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{8,100}$"
    }
  },
  "required": [
    "seed"
  ]
}
```