openapi: 3.0.0 info: title: Amazon Autocomplete API description: | The Amazon Autocomplete API returns the suggestions Amazon's search box shows while a query is being typed, in the order Amazon shows them, on any of 23 Amazon marketplaces. Each answer holds up to 10 search suggestions, and some also carry the extras Amazon places in the box: a row of refinements (such as "Coffee table by price"), a store row such as a brand's Amazon store or Audible, or a shortcut card such as "Your orders". Set amazon_department to get the suggestions Amazon shows inside one department of the marketplace. **Cross-linking**: Each suggestion's `value` is a ready-made Amazon search query. Pass it, or a refinement option's `value`, as the `q` parameter of the Amazon Search API with the same `amazon_domain` to retrieve the matching products, and its `rh`, when it has one, as the `rh` parameter. A shortcut card's `asin` is the `asin` parameter of the Amazon Product API. The Amazon Search API filters by category_id rather than by department. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Amazon Autocomplete security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Search engine identifier schema: type: string enum: ["amazon_autocomplete"] default: "amazon_autocomplete" - name: q in: query required: true description: >- The partial or full search text to autocomplete. It needs at least one letter or number, and a trailing space asks for the next word. schema: type: string maxLength: 200 - name: amazon_domain in: query required: false description: Amazon marketplace whose search box the suggestions come from. schema: type: string default: "amazon.com" 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"] - name: amazon_department in: query required: false description: >- Department of the marketplace's search box to get suggestions in, such as stripbooks for Books on amazon.com. Each marketplace offers its own departments, listed at https://www.searchapi.io/docs/parameters/amazon/department. schema: type: string default: "aps" 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, or Amazon could not answer the request on any attempt. The body is a bare {"error": ...} rather than a search response, and the search is not billed. 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' search_information: $ref: '#/components/schemas/SearchInformation' suggestions: type: array description: >- The suggestions in the order Amazon's search box shows them, empty when Amazon has none for the query. items: $ref: '#/components/schemas/Suggestion' SearchInformation: type: object properties: query_displayed: type: string description: The query as Amazon read it, lowercased and sometimes rewritten department: type: string description: >- Department Amazon took the suggestions from, aps when the requested department had none for the query and Amazon offered suggestions from All Departments instead Suggestion: type: object required: [position, type, value] properties: position: type: integer description: 1-based position of the suggestion in Amazon's search box type: type: string enum: ["query", "refinement", "store", "shortcut"] description: >- The kind of row Amazon shows: a search query, a row of refinements, a store row such as a brand's Amazon store or Audible, or a shortcut card to an Amazon page such as Your orders or Whole Foods Market value: type: string description: The suggested search text, usable as the q parameter of the Amazon Search API title: type: string description: Heading of a refinement row, store, shortcut or query with a byline as Amazon shows it subtitle: type: string description: Second line Amazon shows under a shortcut rh: type: string description: Refinement a query with a byline applies, usable as the rh parameter of the Amazon Search API asin: type: string description: ASIN of the product a shortcut card opens, usable as the asin parameter of the Amazon Product API link: type: string description: Amazon page the suggestion opens thumbnail: type: string description: Image Amazon shows beside the suggestion options: type: array description: The choices of a refinement row in the order Amazon shows them items: $ref: '#/components/schemas/RefinementOption' RefinementOption: type: object required: [title, value, link] properties: title: type: string description: Label of the choice, such as a price range or a product type value: type: string description: Search text the choice opens, usable as the q parameter of the Amazon Search API rh: type: string description: Refinement the choice applies, usable as the rh parameter of the Amazon Search API link: type: string description: Amazon search page the choice opens thumbnail: type: string description: Image Amazon shows for the choice 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 search page for the query 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 identifier q: type: string description: Search text autocompleted amazon_domain: type: string description: Amazon marketplace the suggestions come from amazon_department: type: string description: Department requested ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong