openapi: 3.0.0 info: title: Amazon Bestsellers API description: | Retrieve Amazon bestseller rankings across all departments and categories, including best sellers, new releases, movers and shakers, most wished for, and most gifted products. **Cross-linking**: The `asin` returned by this API can be used with the Amazon Product API to fetch detailed product information. Pass it as the `asin` parameter. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Amazon Bestsellers Search security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Search engine to use schema: type: string enum: ["amazon_bestsellers"] - name: category_id in: query required: false description: Amazon category slug or numeric sub-category ID schema: type: string pattern: '^[a-zA-Z0-9\-]+$' - name: bestseller_type in: query required: false description: Type of bestseller list to retrieve schema: type: string enum: ["bestsellers", "new_releases", "movers_and_shakers", "most_wished_for", "most_gifted"] default: "bestsellers" - name: amazon_domain in: query required: false description: Amazon domain to search schema: type: string enum: ["amazon.ae", "amazon.ca", "amazon.co.jp", "amazon.co.uk", "amazon.com", "amazon.com.au", "amazon.com.be", "amazon.com.br", "amazon.com.tr", "amazon.com.mx", "amazon.de", "amazon.es", "amazon.eg", "amazon.fr", "amazon.in", "amazon.ie", "amazon.it", "amazon.nl", "amazon.pl", "amazon.sa", "amazon.se", "amazon.sg", "amazon.co.za"] default: "amazon.com" - name: language in: query required: false description: Display language for the Amazon page schema: type: string enum: ["ar_SA", "ar_EG", "ar_AE", "zh_CN", "nl_NL", "nl_BE", "en_AE", "en_GB", "fr_FR", "fr_BE", "de_DE", "it_IT", "ja_JP", "pl_PL", "pt_BR", "es_ES", "es_MX", "es_US", "se_SE", "tr_TR"] - name: delivery_country in: query required: false description: Two-letter ISO 3166-1 alpha-2 country code for the delivery address. Defaults to the country of the selected Amazon domain. schema: type: string enum: ["dz", "ao", "bh", "bw", "cm", "eg", "gh", "il", "jo", "ke", "kw", "kg", "mu", "yt", "ma", "na", "ng", "om", "ps", "qa", "re", "sa", "sn", "za", "tz", "tn", "ug", "ae", "zw", "ar", "aw", "bb", "bz", "bm", "bo", "br", "ca", "ky", "cl", "co", "cr", "do", "ec", "sv", "gf", "gp", "gt", "hn", "jm", "mq", "mx", "pa", "py", "pe", "kn", "mf", "tt", "uy", "ve", "au", "bd", "kh", "cn", "fj", "hk", "in", "id", "jp", "kz", "mo", "my", "mh", "fm", "nc", "nz", "pk", "pw", "ph", "sg", "kr", "lk", "tw", "th", "vn", "al", "ad", "am", "at", "by", "be", "ba", "bg", "hr", "cy", "cz", "dk", "ee", "fo", "fi", "fr", "ge", "de", "gi", "gr", "hu", "is", "ie", "it", "lv", "li", "lt", "lu", "mt", "md", "mc", "me", "nl", "mk", "no", "pl", "pt", "ro", "ru", "sm", "rs", "sk", "si", "es", "se", "ch", "tr", "ua", "gb", "us", "va"] - name: page in: query required: false description: Page number for pagination. Maximum of 2 pages per category. Pagination requires a category_id. schema: type: integer minimum: 1 maximum: 2 default: 1 responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' categories: type: array description: Category hierarchy with the current category marked as selected and its subcategories items: $ref: '#/components/schemas/Category' bestsellers: type: array description: List of bestseller products items: $ref: '#/components/schemas/Bestseller' pagination: $ref: '#/components/schemas/Pagination' SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Amazon URL for this search html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Search engine used category_id: type: string description: Amazon category identifier bestseller_type: type: string description: Type of bestseller list amazon_domain: type: string description: Amazon domain used language: type: string description: Display language delivery_country: type: string description: Delivery country code page: type: integer description: Page number Category: type: object required: [name] properties: name: type: string description: Name of the category link: type: string description: URL to the category category_id: type: string description: Category slug or numeric ID extracted from the URL, usable as the category_id parameter is_selected: type: boolean description: Whether this is the currently selected category subcategories: type: array description: Child categories within the selected category items: $ref: '#/components/schemas/Subcategory' Subcategory: type: object required: [name] properties: name: type: string description: Name of the subcategory link: type: string description: URL to the subcategory category_id: type: string description: Category slug or numeric ID extracted from the URL, usable as the category_id parameter Bestseller: type: object required: [position, rank, title, asin, link] properties: position: type: integer description: Position of the item on the current page (1-indexed) rank: type: integer description: Amazon bestseller rank as displayed on the page (e.g. #51 on page 2) title: type: string description: Product title asin: type: string description: Amazon Standard Identification Number link: type: string description: URL to the product page variant: type: string description: "Product format or variant (e.g. Paperback, Hardcover, Board book)" formats_available: type: integer description: "Number of available product formats" thumbnail: type: string description: URL of the product thumbnail image thumbnail_hd: type: string description: "High resolution product thumbnail URL (900x600)" sales_rank: type: integer description: Current Amazon sales rank (Movers & Shakers only) previous_rank: type: integer description: Previous Amazon sales rank (Movers & Shakers only) is_previously_unranked: type: boolean description: Whether the item was previously unranked (Movers & Shakers only). Present as true when the item is new to rankings. percentage_change: type: number description: "Percentage change in sales rank (Movers & Shakers only)" rating: type: number description: Average customer rating reviews: type: integer description: Number of customer reviews price: type: string description: Formatted price with currency symbol, may include range price_symbol: type: string description: Currency symbol (e.g. "$", "EUR", "£") price_currency: type: string description: ISO 4217 currency code (e.g. "USD", "EUR", "GBP") extracted_price: type: number description: Numeric price value (present for single prices) extracted_price_range: type: object description: Numeric price range (present for price ranges instead of extracted_price) properties: from: type: number description: Low end of the price range to: type: number description: High end of the price range is_price_range: type: boolean description: Whether the price is a range price_per: type: object description: Per-unit pricing information properties: price: type: number description: Per-unit price value unit: type: string description: Unit label (e.g. "count", "100ml") more_offers: type: object description: Additional offers from other sellers properties: lowest_price: type: string description: Formatted lowest price from other offers extracted_lowest_price: type: number description: Numeric lowest price value price_symbol: type: string description: Currency symbol for the lowest price price_currency: type: string description: ISO 4217 currency code for the lowest price link: type: string description: URL to view all offers offers_count: type: integer description: Number of additional offers description: type: string description: Description text of the offers Pagination: type: object properties: current_page: type: integer description: Current page number total_pages: type: integer description: Total number of pages available next_page_link: type: string description: URL to the next page of results ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong