openapi: 3.0.0
info:
  title: Amazon Author API
  description: |
    Retrieve an Amazon author page: the author's name, photo and biography, and their books with format, price, rating, series and other editions, filtered by format and language or searched by keyword.

    **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 Author Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Search engine to use
        schema:
          type: string
          enum:
          - amazon_author
      - name: author_id
        in: query
        required: true
        description: Amazon author ID, as in a book's author link (e.g. `B000AQ0842` in `amazon.com/e/B000AQ0842`).
        schema:
          type: string
          pattern: ^[A-Za-z0-9]{10}$
      - name: q
        in: query
        required: false
        description: Search terms to look for in the author's books. Misspellings are corrected.
        schema:
          type: string
      - name: sort_by
        in: query
        required: false
        description: Order of the books
        schema:
          type: string
          enum:
          - popularity
          - price_low_to_high
          - price_high_to_low
          - average_review
          - newest_arrivals
          - most_reviews
          default: popularity
      - name: book_format
        in: query
        required: false
        description: Lists only books available in this format
        schema:
          type: string
          enum:
          - all
          - kindle
          - audiobook
          - hardcover
          - paperback
          - mass_market_paperback
          - kindle_unlimited
          - prime_reading
          default: all
      - name: book_language
        in: query
        required: false
        description: Lists only books in this language. Use a value from the `languages` of a response, such as German.
        schema:
          type: string
      - name: amazon_domain
        in: query
        required: false
        description: Amazon domain of the author page. Author IDs are the same on every domain.
        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: page
        in: query
        required: false
        description: Page number. Each page has up to 16 books, and Amazon lists at most 560 books per author search.
        schema:
          type: integer
          minimum: 1
          maximum: 35
          default: 1
      - name: language
        in: query
        required: false
        description: Display language for titles and labels
        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: Country for delivery calculations
        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: postal_code
        in: query
        required: false
        description: Postal/ZIP code for the delivery address, used by postal-code marketplaces (e.g. 10001 for US, SW1A 0AA for UK, 10115 for DE). Max 20 characters. Mutually exclusive with delivery_city; see the Amazon delivery location reference for which parameter applies per country.
        schema:
          type: string
          maxLength: 20
      - name: delivery_city
        in: query
        required: false
        description: City for the delivery address in snake_case (e.g. riyadh, abu_dhabi, cairo), used only by city-based marketplaces (Saudi Arabia, UAE, Egypt). Max 100 characters. Mutually exclusive with postal_code; for other countries use postal_code.
        schema:
          type: string
          maxLength: 100
      - name: delivery_area
        in: query
        required: false
        description: Area/district within the city for city-based marketplaces that support it (e.g. business_bay on amazon.ae). Max 100 characters. Optional refinement; must be sent together with delivery_city.
        schema:
          type: string
          maxLength: 100
      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'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        author:
          $ref: '#/components/schemas/Author'
        books:
          type: array
          description: The author's books on this page, one entry per work
          items:
            $ref: '#/components/schemas/Book'
        languages:
          type: array
          description: Languages the author's books are available in, usable as book_language
          items:
            type: string
        asins:
          type: array
          description: ASINs of the up to 112 works in the block this page belongs to
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when Amazon has no author page for the author_id
    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
        author_id:
          type: string
          description: Amazon author ID, as in a book's author link (e.g. `B000AQ0842` in `amazon.com/e/B000AQ0842`).
        q:
          type: string
          description: Search terms to look for in the author's books. Misspellings are corrected.
        sort_by:
          type: string
          description: Order of the books
        book_format:
          type: string
          description: Lists only books available in this format
        book_language:
          type: string
          description: Lists only books in this language. Use a value from the `languages` of a response, such as German.
        amazon_domain:
          type: string
          description: Amazon domain of the author page. Author IDs are the same on every domain.
        page:
          type: integer
          description: Page number. Each page has up to 16 books, and Amazon lists at most 560 books per author search.
        language:
          type: string
          description: Display language for titles and labels
        delivery_country:
          type: string
          description: Country for delivery calculations
        postal_code:
          type: string
          description: Postal/ZIP code for the delivery address, used by postal-code marketplaces (e.g. 10001 for US, SW1A 0AA for UK, 10115 for DE). Max 20 characters. Mutually exclusive with delivery_city; see the Amazon delivery location reference for which parameter applies per country.
        delivery_city:
          type: string
          description: City for the delivery address in snake_case (e.g. riyadh, abu_dhabi, cairo), used only by city-based marketplaces (Saudi Arabia, UAE, Egypt). Max 100 characters. Mutually exclusive with postal_code; for other countries use postal_code.
        delivery_area:
          type: string
          description: Area/district within the city for city-based marketplaces that support it (e.g. business_bay on amazon.ae). Max 100 characters. Optional refinement; must be sent together with delivery_city.
    Author:
      type: object
      required:
      - author_id
      - name
      - link
      properties:
        author_id:
          type: string
          description: Amazon author ID
        name:
          type: string
          description: Author name
        biography:
          type: string
          description: Author biography, paragraphs separated by blank lines
        image:
          type: string
          description: URL of the author photo
        link:
          type: string
          description: URL of the author page
    SearchInformation:
      type: object
      required:
      - total_results
      properties:
        query_displayed:
          type: string
          description: Search terms Amazon applied, after spelling correction
        total_results:
          type: integer
          description: Number of books Amazon has for the author and filters
    Book:
      type: object
      required:
      - position
      - asin
      - title
      - link
      - thumbnail
      - format
      properties:
        position:
          type: integer
          description: Position of the book in the list, counted across pages
        asin:
          type: string
          description: ASIN of the listed edition
        title:
          type: string
          description: Book title
        link:
          type: string
          description: URL of the product page
        thumbnail:
          type: string
          description: URL of the cover image
        format:
          type: string
          description: Format of the listed edition, such as Kindle Edition
        authors:
          type: array
          description: Authors of the book
          items:
            $ref: '#/components/schemas/BookAuthor'
        contributors:
          type: array
          description: Other people credited on the book, such as narrators, translators or publishers
          items:
            $ref: '#/components/schemas/BookContributor'
        series:
          $ref: '#/components/schemas/Series'
        rating:
          type: number
          description: Average customer rating out of 5
        reviews:
          type: integer
          description: Number of customer ratings
        price:
          type: string
          description: Price as displayed, with currency
        extracted_price:
          type: number
          description: Price as a number
        original_price:
          type: string
          description: Reference price the discount is measured against, with currency
        extracted_original_price:
          type: number
          description: Reference price as a number
        original_price_label:
          type: string
          description: Label Amazon gives the reference price
        discount_percentage:
          type: integer
          description: Discount percentage off the reference price
        availability:
          type: string
          description: Availability message, in the display language
        other_formats:
          type: array
          description: Other editions of the same book
          items:
            $ref: '#/components/schemas/BookFormat'
        bestseller:
          $ref: '#/components/schemas/Bestseller'
        editors_pick:
          $ref: '#/components/schemas/EditorsPick'
    BookAuthor:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Author name
        link:
          type: string
          description: URL of the author page
        author_id:
          type: string
          description: Amazon author ID, usable as author_id
    BookContributor:
      type: object
      required:
      - name
      - roles
      properties:
        name:
          type: string
          description: Contributor name
        link:
          type: string
          description: URL of the contributor author page
        author_id:
          type: string
          description: Amazon author ID, usable as author_id
        roles:
          type: array
          description: Roles of the contributor, such as narrator, translator or publisher
          items:
            type: string
    Series:
      type: object
      required:
      - title
      properties:
        title:
          type: string
          description: Series title
        link:
          type: string
          description: URL of the series page
        position:
          type: integer
          description: Position of the book in the series
        total:
          type: integer
          description: Number of books in the series
    Bestseller:
      type: object
      properties:
        link:
          type: string
          description: URL of the Best Sellers list
        category:
          type: string
          description: Best Sellers category
        rank:
          type: integer
          description: Best Sellers rank
    EditorsPick:
      type: object
      required:
      - category
      properties:
        link:
          type: string
          description: URL of the editors' pick list
        category:
          type: string
          description: Editors' pick list the book is on
    BookFormat:
      type: object
      required:
      - asin
      - format
      properties:
        asin:
          type: string
          description: ASIN of the edition
        format:
          type: string
          description: Format of the edition
        link:
          type: string
          description: URL of the edition
        price:
          type: string
          description: Price as displayed, with currency
        extracted_price:
          type: number
          description: Price as a number
    Pagination:
      type: object
      required:
      - current
      - total_pages
      properties:
        current:
          type: integer
          description: Current page number
        next:
          type: integer
          description: Next page number
        total_pages:
          type: integer
          description: Number of pages Amazon lists, at most 35
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
