openapi: 3.0.0
info:
  title: Amazon Store API
  description: |
    Retrieve an Amazon brand store: its details, its pages, the number of products it lists, their ASINs, and products with prices, ratings, availability and sellers. Search inside the store with `q`.

    **Cross-linking**: Take `store_id` from `product.brand_store.id` in the Amazon Product API. The `asin` returned by this API can be passed to the Amazon Product API as the `asin` parameter.
  version: 1.0.0
servers:
- url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Amazon Store Search
      security:
      - ApiKeyAuth: []
      - ApiKeyQuery: []
      parameters:
      - name: engine
        in: query
        required: true
        description: Search engine to use
        schema:
          type: string
          enum:
          - amazon_store
      - name: store_id
        in: query
        required: true
        description: Page ID of the brand store. Any page of the store works. The Amazon Product API returns it as `product.brand_store.id`.
        schema:
          type: string
          pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$
      - name: q
        in: query
        required: false
        description: Search terms to look for inside the store. Without it, every product of the store is listed.
        schema:
          type: string
      - name: amazon_domain
        in: query
        required: false
        description: Amazon domain the store belongs to. Store IDs are specific to one 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 25 products, and a store lists at most 500.
        schema:
          type: integer
          minimum: 1
          maximum: 20
          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'
        store:
          $ref: '#/components/schemas/Store'
        pages:
          type: array
          description: Pages of the store, in the order the store displays them
          items:
            $ref: '#/components/schemas/Page'
        products:
          type: array
          description: Products on this page
          items:
            $ref: '#/components/schemas/Product'
        asins:
          type: array
          description: ASINs of every product the store lists for the search, up to 500
          items:
            type: string
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message when Amazon has no store for the store_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
        store_id:
          type: string
          description: Page ID of the brand store. Any page of the store works. The Amazon Product API returns it as `product.brand_store.id`.
        q:
          type: string
          description: Search terms to look for inside the store. Without it, every product of the store is listed.
        amazon_domain:
          type: string
          description: Amazon domain the store belongs to. Store IDs are specific to one domain.
        page:
          type: integer
          description: Page number. Each page has up to 25 products, and a store lists at most 500.
        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.
    Store:
      type: object
      required:
      - store_id
      - name
      - link
      properties:
        store_id:
          type: string
          description: Page ID of the store home page
        name:
          type: string
          description: Brand name of the store
        description:
          type: string
          description: Description of the store
        brand_id:
          type: string
          description: Amazon brand ID
        entity_type:
          type: string
          description: Type of entity that owns the store, such as brand or vendor
        logo:
          type: string
          description: URL of the brand logo
        link:
          type: string
          description: URL of the store
    SearchInformation:
      type: object
      required:
      - total_results
      properties:
        query_displayed:
          type: string
          description: Search terms Amazon applied; * stands for every product
        total_results:
          type: integer
          description: Number of products the store has for the search
    Page:
      type: object
      required:
      - page_id
      - title
      - link
      - level
      properties:
        page_id:
          type: string
          description: ID of the page, usable as store_id
        title:
          type: string
          description: Page title
        link:
          type: string
          description: URL of the page
        level:
          type: integer
          description: Depth of the page in the store, starting at 1 for the home page
        parent_id:
          type: string
          description: ID of the parent page
    Product:
      type: object
      required:
      - position
      - asin
      - title
      - link
      - thumbnail
      properties:
        position:
          type: integer
          description: Position of the product in the store 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
        recent_sales:
          type: string
          description: Recent sales volume as displayed
        extracted_recent_sales:
          type: integer
          description: Recent sales volume as a number
        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, such as List or M.R.P
        discount_percentage:
          type: integer
          description: Discount percentage off the reference price
        availability:
          type: string
          description: Availability message, in the display language
        fulfillment:
          $ref: '#/components/schemas/Fulfillment'
    Fulfillment:
      type: object
      properties:
        ships_from:
          type: string
          description: Name of the party that ships the product
        sold_by:
          type: string
          description: Name of the seller
        third_party_seller:
          $ref: '#/components/schemas/ThirdPartySeller'
    ThirdPartySeller:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          description: Amazon seller ID
        name:
          type: string
          description: Name of the seller
    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 the store lists for the search
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
