openapi: 3.0.0
info:
  title: Amazon Book Charts API
  description: |
    Retrieve the weekly Amazon Book Charts: the top 20 most sold and most read books in fiction and nonfiction, with rank, weeks on the chart, rank movement, rating and editions, for the latest or any past week.

    **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 Book Charts Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Search engine to use
        schema:
          type: string
          enum:
          - amazon_book_charts
      - name: chart_type
        in: query
        required: false
        description: 'Chart to retrieve: books ranked by copies sold or by how much they are read'
        schema:
          type: string
          enum:
          - most_sold
          - most_read
          default: most_sold
      - name: category
        in: query
        required: false
        description: Book category of the chart
        schema:
          type: string
          enum:
          - fiction
          - nonfiction
          default: fiction
      - name: week
        in: query
        required: false
        description: Any day of the chart week, in YYYY-MM-DD format. Defaults to the latest published week.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      - name: amazon_domain
        in: query
        required: false
        description: Amazon domain of the chart
        schema:
          type: string
          enum:
          - amazon.com
          - amazon.ca
          - amazon.co.uk
          - amazon.de
          default: amazon.com
      - name: language
        in: query
        required: false
        description: 'Display language. Supported values depend on amazon_domain: en_US and es_US on amazon.com, en_CA and fr_CA on amazon.ca, en_GB on amazon.co.uk, de_DE and en_GB on amazon.de.'
        schema:
          type: string
          enum:
          - en_US
          - es_US
          - en_CA
          - fr_CA
          - en_GB
          - de_DE
      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'
        chart_information:
          $ref: '#/components/schemas/ChartInformation'
        books:
          type: array
          description: Books on the chart, in rank order
          items:
            $ref: '#/components/schemas/Book'
        error:
          type: string
          description: Error message when Amazon has no chart for the request
    SearchMetadata:
      type: object
      required:
      - 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
        chart_type:
          type: string
          description: 'Chart to retrieve: books ranked by copies sold or by how much they are read'
        category:
          type: string
          description: Book category of the chart
        week:
          type: string
          description: Any day of the chart week, in YYYY-MM-DD format. Defaults to the latest published week.
        amazon_domain:
          type: string
          description: Amazon domain of the chart
        language:
          type: string
          description: 'Display language. Supported values depend on amazon_domain: en_US and es_US on amazon.com, en_CA and fr_CA on amazon.ca, en_GB on amazon.co.uk, de_DE and en_GB on amazon.de.'
    ChartInformation:
      type: object
      required:
      - chart_type
      - category
      - week
      properties:
        chart_type:
          type: string
          description: Chart retrieved, most_sold or most_read
        category:
          type: string
          description: Book category, fiction or nonfiction
        week:
          type: string
          format: date
          description: Sunday that ends the chart week
        previous_week:
          type: string
          format: date
          description: Sunday that ends the previous chart week
        next_week:
          type: string
          format: date
          description: Sunday that ends the next chart week
    Book:
      type: object
      required:
      - position
      - asin
      - title
      - link
      - thumbnail
      - weeks_on_chart
      properties:
        position:
          type: integer
          description: Rank on the chart
        asin:
          type: string
          description: ASIN or ISBN-10 of the edition the chart links to
        title:
          type: string
          description: Book title
        link:
          type: string
          description: URL of the product page
        thumbnail:
          type: string
          description: URL of the cover image
        author:
          type: string
          description: Author of the book
        rating:
          type: number
          description: Average customer rating out of 5
        reviews:
          type: integer
          description: Number of customer ratings
        weeks_on_chart:
          type: integer
          description: Number of weeks the book has been on the chart
        is_first_week:
          type: boolean
          description: Whether this is the book's first week on the chart
        previous_position:
          type: integer
          description: Rank on the previous week's chart, when the book moved
        kindle_asin:
          type: string
          description: ASIN of the Kindle edition
        audiobook_asin:
          type: string
          description: ASIN of the audiobook edition
        audiobook_sample:
          type: string
          description: URL of the audiobook sample
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
