openapi: 3.0.0
info:
  title: AliExpress Search API
  description: |
    Search AliExpress products by keyword for any ship-to country, in its currency and language, with sorting, price, free shipping, Choice, ships-from and attribute filters and up to 60 pages of 60 products.
    Each product returns its price, original price and discount, rating, orders, ships-from country, delivery estimate, badges, category ids and images, and each page returns its filters and related searches.

    **Cross-linking**: The `value` of an option in `filters` goes in the parameter its filter names, `attribute_ids` or `ships_from`.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: AliExpress Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine used to retrieve the results.
          schema:
            type: string
            enum: ["aliexpress_search"]
        - name: q
          in: query
          required: true
          description: Search terms, with at least one character other than a hyphen.
          schema:
            type: string
            maxLength: 200
            pattern: '[^\s-]'
        - name: delivery_country
          in: query
          required: false
          description: Two-letter code of the country the products ship to. It also sets the currency and language AliExpress uses there unless `currency` or `language` is given.
          schema:
            type: string
            enum: ["AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "BV", "BW", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CO", "CR", "CV", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "ST", "SV", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW"]
            default: "US"
        - name: currency
          in: query
          required: false
          description: Three-letter code of the currency prices are shown in.
          schema:
            type: string
            enum: ["AED", "AMD", "ARS", "AUD", "AZN", "BDT", "BGN", "BHD", "BOB", "BRL", "BYN", "CAD", "CHF", "CLP", "CNY", "COP", "CRC", "CZK", "DKK", "DOP", "DZD", "EGP", "EUR", "FJD", "GBP", "GEL", "GTQ", "HKD", "HNL", "HUF", "IDR", "ILS", "INR", "ISK", "JOD", "JPY", "KES", "KGS", "KHR", "KRW", "KWD", "KZT", "LAK", "LKR", "MAD", "MDL", "MMK", "MNT", "MUR", "MXN", "MYR", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PHP", "PKR", "PLN", "QAR", "RON", "RSD", "RUB", "SAR", "SEK", "SGD", "THB", "TND", "TRY", "TWD", "UAH", "USD", "UYU", "UZS", "VND", "XAF", "XOF", "XPF", "ZAR"]
        - name: language
          in: query
          required: false
          description: Language of titles, badges and filters.
          schema:
            type: string
            enum: ["ar_MA", "de_DE", "en_US", "es_ES", "fr_FR", "he_IL", "id_ID", "it_IT", "ja_JP", "ko_KR", "nl_NL", "pl_PL", "pt_BR", "th_TH", "tr_TR", "uk_UA"]
        - name: sort_by
          in: query
          required: false
          description: Order of the products.
          schema:
            type: string
            enum: ["best_match", "best_seller", "price_low_to_high", "price_high_to_low"]
            default: "best_match"
        - name: price_min
          in: query
          required: false
          description: Lowest price, in the currency of the results.
          schema:
            type: number
            minimum: 0
            maximum: 1000000
        - name: price_max
          in: query
          required: false
          description: Highest price, in the currency of the results. Must be at least `price_min`.
          schema:
            type: number
            minimum: 0
            maximum: 1000000
        - name: is_free_shipping
          in: query
          required: false
          description: Set to `true` to return only products with free shipping.
          schema:
            type: boolean
        - name: is_choice
          in: query
          required: false
          description: Set to `true` to return only AliExpress Choice products.
          schema:
            type: boolean
        - name: ships_from
          in: query
          required: false
          description: Country code the products ship from, as given by the `ships_from` filter, such as `US`.
          schema:
            type: string
            pattern: '^\s*[A-Za-z]{2}\s*$'
        - name: attribute_ids
          in: query
          required: false
          description: Comma-separated attribute values from the `attribute_ids` filters, such as `3079-4148343,3203-4163876`, up to 20.
          schema:
            type: string
            pattern: '^\s*\d{1,12}-\d{1,12}(,\d{1,12}-\d{1,12}){0,19}\s*$'
        - name: page
          in: query
          required: false
          description: Page of results. AliExpress shows up to 60 pages of 60 products.
          schema:
            type: integer
            minimum: 1
            maximum: 60
            default: 1
      responses:
        '200':
          description: Successful response. A search AliExpress answers without products carries an error.
          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
      required: [search_metadata, search_parameters]
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        organic_results:
          type: array
          description: Products on the requested page, in AliExpress's order.
          items:
            $ref: '#/components/schemas/OrganicResult'
        filters:
          type: array
          description: Filters AliExpress offers for the search.
          items:
            $ref: '#/components/schemas/Filter'
        related_searches:
          type: array
          description: Searches AliExpress relates to this one.
          items:
            $ref: '#/components/schemas/RelatedSearch'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search has no products.
    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: "AliExpress 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
      required: [engine, q]
      properties:
        engine:
          type: string
          description: Engine used for the search.
        q:
          type: string
          description: Search terms.
        delivery_country:
          type: string
          description: Ship-to country.
        currency:
          type: string
          description: Currency of the prices.
        language:
          type: string
          description: Language of the results.
        sort_by:
          type: string
          description: Order of the products.
        price_min:
          type: number
          description: Lowest price.
        price_max:
          type: number
          description: Highest price.
        is_free_shipping:
          type: boolean
          description: Whether only products with free shipping were asked for.
        is_choice:
          type: boolean
          description: Whether only AliExpress Choice products were asked for.
        ships_from:
          type: string
          description: Ships-from country.
        attribute_ids:
          type: string
          description: Attribute values filtered on.
        page:
          type: integer
          description: Page of results.
    SearchInformation:
      type: object
      properties:
        total_results:
          type: integer
          description: Number of products AliExpress reports for the search, an estimate that can change from page to page.
        translated_query:
          type: string
          description: Search terms AliExpress searched after translating or correcting `q`.
        currency:
          type: string
          description: Three-letter code of the currency the prices are in.
    OrganicResult:
      type: object
      required: [position, product_id, title, link, thumbnail, is_sponsored, is_choice, has_free_shipping_badge, is_new_shopper_price]
      properties:
        position:
          type: integer
          description: Position of the product on the page.
        product_id:
          type: string
          description: AliExpress product id.
        title:
          type: string
          description: Product title.
        link:
          type: string
          description: Link to the product page.
        price:
          type: string
          description: Price as AliExpress shows it.
        extracted_price:
          type: number
          description: Price as a number.
        original_price:
          type: string
          description: Price before the discount, as AliExpress shows it.
        extracted_original_price:
          type: number
          description: Price before the discount, as a number.
        discount:
          type: integer
          description: Discount in percent.
        rating:
          type: number
          description: Average star rating, out of 5.
        sold:
          type: string
          description: Number of orders as AliExpress shows it.
        extracted_sold:
          type: integer
          description: Number of orders.
        ships_from:
          type: string
          description: Country code the product ships from, as AliExpress gives it.
        delivery:
          $ref: '#/components/schemas/Delivery'
        badges:
          type: array
          description: Labels AliExpress shows on the product.
          items:
            type: string
        sku_id:
          type: string
          description: Id of the product variant the price is for.
        category_ids:
          type: array
          description: Ids of the product's categories, from the top category to its own.
          items:
            type: string
        listed_date:
          type: string
          format: date
          description: Date the product was listed.
        thumbnail:
          type: string
          description: Main product image.
        images:
          type: array
          description: Product images.
          items:
            type: string
        is_sponsored:
          type: boolean
          description: Whether the product is an ad.
        is_choice:
          type: boolean
          description: Whether the product is an AliExpress Choice product.
        has_free_shipping_badge:
          type: boolean
          description: Whether the product shows a free shipping badge.
        is_new_shopper_price:
          type: boolean
          description: Whether the price shown is AliExpress's offer for new shoppers.
    Delivery:
      type: object
      description: Delivery estimate for the ship-to country.
      properties:
        min_days:
          type: integer
          description: Fewest days to deliver.
        max_days:
          type: integer
          description: Most days to deliver.
        from_date:
          type: string
          format: date
          description: Earliest delivery date.
        to_date:
          type: string
          format: date
          description: Latest delivery date.
    Filter:
      type: object
      required: [name, parameter, options]
      properties:
        name:
          type: string
          description: Filter name, such as Brand or Main color.
        parameter:
          type: string
          enum: ["attribute_ids", "ships_from"]
          description: Parameter an option's value goes in.
        options:
          type: array
          description: Values the filter offers.
          items:
            $ref: '#/components/schemas/FilterOption'
    FilterOption:
      type: object
      required: [name, value, is_selected]
      properties:
        name:
          type: string
          description: Option name.
        value:
          type: string
          description: Value to pass in the filter's parameter.
        is_selected:
          type: boolean
          description: Whether the search is filtered on this option.
    RelatedSearch:
      type: object
      required: [query]
      properties:
        query:
          type: string
          description: Related search terms.
        link:
          type: string
          description: Link to the related search on AliExpress.
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page.
        next:
          type: integer
          description: Next page.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
