openapi: 3.0.0
info:
  title: Amazon Deals API
  description: |
    Retrieve Amazon's Today's Deals: deal price, reference price, discount, deal type, claimed percentage and start and end times, filtered by department, brand, price, discount, lightning deals and Prime programs.

    **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 Deals Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Search engine to use
        schema:
          type: string
          enum:
          - amazon_deals
      - name: amazon_domain
        in: query
        required: false
        description: Amazon domain to list deals from
        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: category_id
        in: query
        required: false
        description: Deals department ID that limits the list to one department. Take it from the `filters` of a response or from the Amazon Categories API with `category_type=deals`.
        schema:
          type: string
          pattern: ^\d+$
      - name: deal_type
        in: query
        required: false
        description: Type of deals to list. `lightning_deal` returns only time-limited lightning deals.
        schema:
          type: string
          enum:
          - all
          - lightning_deal
          default: all
      - name: brand_id
        in: query
        required: false
        description: One or more comma-separated brand IDs. Take them from a deal's `brand_id` or from the `filters` of a response.
        schema:
          type: string
          pattern: ^\d+(,\d+)*$
      - name: price_min
        in: query
        required: false
        description: Minimum deal price, in the marketplace's currency
        schema:
          type: number
          minimum: 0
      - name: price_max
        in: query
        required: false
        description: Maximum deal price, in the marketplace's currency
        schema:
          type: number
          minimum: 0
      - name: discount_min
        in: query
        required: false
        description: Minimum discount percentage
        schema:
          type: integer
          minimum: 0
          maximum: 100
      - name: discount_max
        in: query
        required: false
        description: Maximum discount percentage
        schema:
          type: integer
          minimum: 0
          maximum: 100
      - name: prime_exclusive
        in: query
        required: false
        description: Lists only deals exclusive to Prime members
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: prime_early_access
        in: query
        required: false
        description: Lists only deals Prime members can access early
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: page
        in: query
        required: false
        description: Page number. Each page has up to 30 deals, and Amazon lists at most 500 deals per filter combination.
        schema:
          type: integer
          minimum: 1
          maximum: 17
          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'
        deals:
          type: array
          description: Deals on this page
          items:
            $ref: '#/components/schemas/Deal'
        filters:
          type: array
          description: Filters available for the current deal list
          items:
            $ref: '#/components/schemas/Filter'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when Amazon lists no deals 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
        amazon_domain:
          type: string
          description: Amazon domain to list deals from
        category_id:
          type: string
          description: Deals department ID that limits the list to one department. Take it from the `filters` of a response or from the Amazon Categories API with `category_type=deals`.
        deal_type:
          type: string
          description: Type of deals to list. `lightning_deal` returns only time-limited lightning deals.
        brand_id:
          type: string
          description: One or more comma-separated brand IDs. Take them from a deal's `brand_id` or from the `filters` of a response.
        price_min:
          type: number
          description: Minimum deal price, in the marketplace's currency
        price_max:
          type: number
          description: Maximum deal price, in the marketplace's currency
        discount_min:
          type: integer
          description: Minimum discount percentage
        discount_max:
          type: integer
          description: Maximum discount percentage
        prime_exclusive:
          type: string
          description: Lists only deals exclusive to Prime members
        prime_early_access:
          type: string
          description: Lists only deals Prime members can access early
        page:
          type: integer
          description: Page number. Each page has up to 30 deals, and Amazon lists at most 500 deals per filter combination.
        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.
    Deal:
      type: object
      required:
      - position
      - asin
      - title
      - link
      - thumbnail
      - brand_id
      - category_ids
      properties:
        position:
          type: integer
          description: Position of the deal in the list, counted across pages
        asin:
          type: string
          description: Amazon Standard Identification Number of the product
        title:
          type: string
          description: Product title
        link:
          type: string
          description: URL of the product page
        thumbnail:
          type: string
          description: URL of the product image
        rating:
          type: number
          description: Average customer rating out of 5
        reviews:
          type: integer
          description: Number of customer ratings
        price:
          type: string
          description: Deal price as displayed, with currency
        extracted_price:
          type: number
          description: Deal 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, such as List or Typical
        discount_percentage:
          type: integer
          description: Discount percentage shown on the deal
        deal_id:
          type: string
          description: Amazon identifier of the deal
        deal_type:
          type: string
          description: Type of deal, such as best_deal or lightning_deal
        is_prime_exclusive:
          type: boolean
          description: Whether the deal is only available to Prime members
        is_prime_early_access:
          type: boolean
          description: Whether Prime members can access the deal early
        deal_badge:
          type: string
          description: Badge text shown on the deal, in the display language
        percent_claimed:
          type: number
          description: Percentage of the deal already claimed
        starts_at:
          type: string
          format: date-time
          description: Time the deal started, in UTC
        ends_at:
          type: string
          format: date-time
          description: Time the deal ends, in UTC
        brand_id:
          type: string
          description: Brand ID, usable as the brand_id parameter
        category_ids:
          type: array
          description: IDs of the departments the product belongs to, usable as the category_id parameter
          items:
            type: string
    Filter:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: Filter name, in the display language
        min:
          type: number
          description: Lowest value available for a range filter
        max:
          type: number
          description: Highest value available for a range filter
        options:
          type: array
          description: Selectable options of the filter
          items:
            $ref: '#/components/schemas/FilterOption'
    FilterOption:
      type: object
      required:
      - text
      - value
      properties:
        text:
          type: string
          description: Option label, in the display language
        value:
          type: string
          description: 'Value to send: a department ID for category_id, a brand ID for brand_id, or the name of the Prime parameter to set to true'
        is_selected:
          type: boolean
          description: Whether the option is applied to the current list
    Pagination:
      type: object
      required:
      - current
      properties:
        current:
          type: integer
          description: Current page number
        next:
          type: integer
          description: Next page number
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
