openapi: 3.0.0
info:
  title: Alibaba Search API
  description: |
    Search Alibaba.com products by keyword, with supplier country, Verified and Verified PRO supplier, Trade Assurance, ready to ship, free sample, minimum order, price and category filters, in 19 languages and 39 currencies, up to 100 pages of up to 100 products.
    Each product returns its price range with any promotion and discount, quantity price tiers, minimum order, category, images and certifications, and its supplier's country, years on Alibaba, badges, rating, response rate and audits.

    **Cross-linking**: The `category_id` of a product goes in the `category_id` parameter to search within its category.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Alibaba Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine used to retrieve the results.
          schema:
            type: string
            enum: ["alibaba_search"]
        - name: q
          in: query
          required: true
          description: Search terms.
          schema:
            type: string
            maxLength: 200
        - name: category_id
          in: query
          required: false
          description: Alibaba category to search within, such as the `category_id` of a product.
          schema:
            type: string
            pattern: '^\s*\d{1,12}\s*$'
        - name: supplier_country
          in: query
          required: false
          description: ISO 3166-1 alpha-2 code of the country the suppliers are based in, such as `CN`, `VN` or `GB`.
          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", "CN", "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"]
        - name: is_verified_supplier
          in: query
          required: false
          description: Set to `true` to return only products from Verified suppliers.
          schema:
            type: boolean
        - name: is_verified_pro_supplier
          in: query
          required: false
          description: Set to `true` to return only products from Verified PRO suppliers.
          schema:
            type: boolean
        - name: has_trade_assurance
          in: query
          required: false
          description: Set to `true` to return only products covered by Trade Assurance.
          schema:
            type: boolean
        - name: is_ready_to_ship
          in: query
          required: false
          description: Set to `true` to return only products that are ready to ship.
          schema:
            type: boolean
        - name: has_free_sample
          in: query
          required: false
          description: Set to `true` to return only products with free samples.
          schema:
            type: boolean
        - name: price_min
          in: query
          required: false
          description: Lowest starting unit price, in USD.
          schema:
            type: number
            minimum: 0
            maximum: 1000000
        - name: price_max
          in: query
          required: false
          description: Highest starting unit price, in USD.
          schema:
            type: number
            minimum: 0
            maximum: 1000000
        - name: moq_min
          in: query
          required: false
          description: Lowest minimum order quantity.
          schema:
            type: integer
            minimum: 1
            maximum: 100000000
        - name: moq_max
          in: query
          required: false
          description: Highest minimum order quantity.
          schema:
            type: integer
            minimum: 1
            maximum: 100000000
        - name: language
          in: query
          required: false
          description: Language of product titles and order units. Alibaba returns supplier ratings for English only.
          schema:
            type: string
            enum: ["ar", "de", "en", "es", "fr", "he", "hi", "id", "it", "ja", "ko", "nl", "pl", "pt", "ru", "th", "tr", "vi", "zh"]
            default: "en"
        - name: currency
          in: query
          required: false
          description: Currency of the prices and price tiers.
          schema:
            type: string
            enum: ["AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "IDR", "ILS", "INR", "JPY", "KRW", "KZT", "MXN", "MYR", "NGN", "NOK", "NZD", "PHP", "PKR", "PLN", "RUB", "SAR", "SEK", "SGD", "THB", "TRY", "TWD", "UAH", "USD", "VND", "ZAR"]
            default: "USD"
        - name: num
          in: query
          required: false
          description: Number of products per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 48
        - name: page
          in: query
          required: false
          description: Page of results. Alibaba shows up to 100 pages.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 1
      responses:
        '200':
          description: Successful response. A search Alibaba 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 Alibaba's order.
          items:
            $ref: '#/components/schemas/Product'
        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: "Alibaba 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 to retrieve the results.
        q:
          type: string
          description: Search terms.
        category_id:
          type: string
          description: Alibaba category searched within.
        supplier_country:
          type: string
          description: Two-letter code of the country the suppliers are based in.
        is_verified_supplier:
          type: boolean
          description: Whether only products from Verified suppliers were asked for.
        is_verified_pro_supplier:
          type: boolean
          description: Whether only products from Verified PRO suppliers were asked for.
        has_trade_assurance:
          type: boolean
          description: Whether only products covered by Trade Assurance were asked for.
        is_ready_to_ship:
          type: boolean
          description: Whether only ready to ship products were asked for.
        has_free_sample:
          type: boolean
          description: Whether only products with free samples were asked for.
        price_min:
          type: number
          description: Lowest starting unit price, in USD.
        price_max:
          type: number
          description: Highest starting unit price, in USD.
        moq_min:
          type: integer
          description: Lowest minimum order quantity.
        moq_max:
          type: integer
          description: Highest minimum order quantity.
        language:
          type: string
          description: Language of product titles and order units.
          enum: ["ar", "de", "en", "es", "fr", "he", "hi", "id", "it", "ja", "ko", "nl", "pl", "pt", "ru", "th", "tr", "vi", "zh"]
        currency:
          type: string
          description: Currency of the prices and price tiers.
          enum: ["AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "IDR", "ILS", "INR", "JPY", "KRW", "KZT", "MXN", "MYR", "NGN", "NOK", "NZD", "PHP", "PKR", "PLN", "RUB", "SAR", "SEK", "SGD", "THB", "TRY", "TWD", "UAH", "USD", "VND", "ZAR"]
        num:
          type: integer
          description: Number of products per page.
        page:
          type: integer
          description: Page of results.
    SearchInformation:
      type: object
      required: [total_results]
      properties:
        total_results:
          type: integer
          description: Number of products Alibaba estimates for the search, which can vary between requests.
    Product:
      type: object
      required: [position, product_id, title, link, price, extracted_price_min, extracted_price_max, minimum_order, thumbnail, has_video, is_sponsored, supplier]
      properties:
        position:
          type: integer
          description: Position of the product on the page.
        product_id:
          type: string
          description: Alibaba product ID.
        title:
          type: string
          description: Product title.
        link:
          type: string
          description: URL of the product page.
        price:
          type: string
          description: Price range as Alibaba shows it, after any promotion, in the requested currency.
        extracted_price_min:
          type: number
          description: Lowest unit price in the price range.
        extracted_price_max:
          type: number
          description: Highest unit price in the price range.
        original_price:
          type: string
          description: Price range before the promotion, as Alibaba shows it.
        extracted_original_price_min:
          type: number
          description: Lowest unit price before the promotion.
        extracted_original_price_max:
          type: number
          description: Highest unit price before the promotion.
        discount:
          type: integer
          description: Percent off in the promotion.
        price_tiers:
          type: array
          description: Unit prices by order quantity.
          items:
            $ref: '#/components/schemas/PriceTier'
        minimum_order:
          type: string
          description: Minimum order as Alibaba shows it.
        extracted_minimum_order:
          type: integer
          description: Minimum order quantity.
        unit:
          type: string
          description: Unit the order quantities count.
        category:
          type: string
          description: Name of the product's category.
        category_id:
          type: string
          description: ID of the product's category.
        thumbnail:
          type: string
          description: URL of the product's main image.
        images:
          type: array
          description: URLs of the product's images.
          items:
            type: string
        has_video:
          type: boolean
          description: Whether the product has a video.
        certifications:
          type: array
          description: Certifications listed for the product.
          items:
            type: string
        is_sponsored:
          type: boolean
          description: Whether the product is an ad.
        supplier:
          $ref: '#/components/schemas/Supplier'
    PriceTier:
      type: object
      required: [min_quantity, price, extracted_price]
      properties:
        min_quantity:
          type: integer
          description: Smallest order quantity this unit price applies to.
        max_quantity:
          type: integer
          description: Largest order quantity this unit price applies to.
        price:
          type: string
          description: Unit price as Alibaba shows it.
        extracted_price:
          type: number
          description: Unit price.
        promotion_price:
          type: string
          description: Discounted unit price as Alibaba shows it.
        extracted_promotion_price:
          type: number
          description: Discounted unit price.
    Supplier:
      type: object
      required: [name, id, link, country_code, is_gold_supplier, is_verified, is_verified_pro, has_trade_assurance]
      properties:
        name:
          type: string
          description: Supplier name.
        id:
          type: string
          description: Alibaba supplier ID.
        link:
          type: string
          description: URL of the supplier's profile.
        country:
          type: string
          description: Country the supplier is based in.
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 code of the country the supplier is based in, such as `CN` or `GB`.
        years_on_platform:
          type: integer
          description: Years the supplier has sold on Alibaba.
        is_gold_supplier:
          type: boolean
          description: Whether the supplier is a Gold Supplier.
        is_verified:
          type: boolean
          description: Whether the supplier is a Verified supplier.
        is_verified_pro:
          type: boolean
          description: Whether the supplier is a Verified PRO supplier.
        has_trade_assurance:
          type: boolean
          description: Whether the supplier offers Trade Assurance.
        response_rate:
          type: string
          description: Share of messages the supplier answers.
        response_time:
          type: string
          description: Time the supplier usually takes to answer.
        rating:
          type: number
          description: Supplier's average review score out of 5.
        reviews:
          type: integer
          description: Number of reviews of the supplier.
        ratings:
          $ref: '#/components/schemas/SupplierRatings'
        audits:
          type: array
          description: Audits the supplier has passed.
          items:
            type: string
    SupplierRatings:
      type: object
      properties:
        product:
          type: number
          description: Average product quality score out of 5.
        service:
          type: number
          description: Average supplier service score out of 5.
        shipping:
          type: number
          description: Average on-time shipping score out of 5.
    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
