openapi: 3.0.0
info:
  title: AliExpress Product Reviews API
  description: |
    Get the reviews of an AliExpress product, 20 per page for up to 250 pages, sorted by relevance or newest first, filtered by star rating, photos, additional reviews or the shopper's country, and translated to the requested language.
    Each review returns its star rating, date and reviewer. When AliExpress has them, a review also returns the text, the buyer's original text, variant bought, shipping method, photos, rated aspects, the seller's response and an additional review. A page also returns the product's average rating, review count and star histogram, review counts per filter and, when AliExpress has them, the topics buyers mention.

    **Cross-linking**: `product_id` takes the `product_id` of an `aliexpress_search` result. The `filter` of an entry in `filters` goes in the `filter` parameter.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: AliExpress Product Reviews
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine used to retrieve the results.
          schema:
            type: string
            enum: ["aliexpress_product_reviews"]
        - name: product_id
          in: query
          required: true
          description: AliExpress product ID, the number in the product link, such as `1005007502032342`. It can be at most `9223372036854775807`.
          schema:
            type: string
            pattern: '^\s*0*[1-9]\d{0,18}\s*$'
        - name: sort_by
          in: query
          required: false
          description: Order of the reviews.
          schema:
            type: string
            enum: ["relevance", "newest"]
            default: "relevance"
        - name: rating
          in: query
          required: false
          description: Star rating of the reviews to return. Cannot be used with `filter`.
          schema:
            type: string
            enum: ["1", "2", "3", "4", "5"]
        - name: filter
          in: query
          required: false
          description: Returns only reviews with photos, with an additional review, or from shoppers in `delivery_country`. Cannot be used with `rating`.
          schema:
            type: string
            enum: ["with_images", "with_additional_review", "from_delivery_country"]
        - name: delivery_country
          in: query
          required: false
          description: Two-letter code of the shopper's country, used by the `from_delivery_country` filter.
          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: language
          in: query
          required: false
          description: Language the reviews and topics are translated to.
          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"]
            default: "en_US"
        - name: page
          in: query
          required: false
          description: Page of reviews. AliExpress shows up to 250 pages of 20 reviews.
          schema:
            type: integer
            minimum: 1
            maximum: 250
            default: 1
      responses:
        '200':
          description: Successful response. A product or page without reviews 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'
        product:
          $ref: '#/components/schemas/Product'
        filters:
          type: array
          description: Review filters with the number of reviews each one returns.
          items:
            $ref: '#/components/schemas/Filter'
        topics:
          type: array
          description: Topics buyers mention in their reviews.
          items:
            $ref: '#/components/schemas/Topic'
        reviews:
          type: array
          description: Reviews on the requested page, in AliExpress's order.
          items:
            $ref: '#/components/schemas/Review'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Message explaining why the search has no reviews.
    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 product page"
        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, product_id]
      properties:
        engine:
          type: string
          description: Engine used for the search.
        product_id:
          type: string
          description: AliExpress product ID.
        sort_by:
          type: string
          description: Order of the reviews.
        rating:
          type: string
          description: Star rating filtered on.
        filter:
          type: string
          description: Review filter applied.
        delivery_country:
          type: string
          description: Shopper's country.
        language:
          type: string
          description: Language of the reviews.
        page:
          type: integer
          description: Page of reviews.
    SearchInformation:
      type: object
      properties:
        total_results:
          type: integer
          description: Number of reviews that match the rating or filter.
    Product:
      type: object
      required: [product_id]
      properties:
        product_id:
          type: string
          description: AliExpress product ID.
        rating:
          type: number
          description: Average star rating of the product.
        reviews:
          type: integer
          description: Number of ratings the product has.
        reviews_histogram:
          type: object
          description: Number of ratings for each star rating, keyed from `1` to `5`.
          additionalProperties:
            type: integer
        positive_percentage:
          type: number
          description: Percentage of ratings with 4 or 5 stars.
        has_aggregated_reviews:
          type: boolean
          description: Whether AliExpress fills the listing's reviews and ratings from other sellers' similar items.
    Filter:
      type: object
      required: [filter, is_selected]
      properties:
        filter:
          type: string
          description: Value to pass in the `filter` parameter.
          enum: ["with_images", "with_additional_review", "from_delivery_country"]
        reviews:
          type: integer
          description: Number of reviews the filter returns.
        is_selected:
          type: boolean
          description: Whether the filter is applied to this page.
    Topic:
      type: object
      required: [keyword]
      properties:
        keyword:
          type: string
          description: Words buyers use about the product.
        reviews:
          type: integer
          description: Number of reviews that mention the topic.
        sentiment:
          type: string
          description: Whether the topic is a positive, neutral or negative remark.
          enum: ["positive", "neutral", "negative"]
    Review:
      type: object
      required: [position, id]
      properties:
        position:
          type: integer
          description: Position of the review across pages.
        id:
          type: string
          description: AliExpress review ID.
        rating:
          type: integer
          description: Star rating from 1 to 5.
        date:
          type: string
          description: Date of the review, as AliExpress writes it.
        text:
          type: string
          description: Review text in the requested language.
        original_text:
          type: string
          description: Review text as the buyer wrote it, when it differs from `text`.
        user:
          $ref: '#/components/schemas/User'
        is_anonymous:
          type: boolean
          description: Whether the buyer posted the review without their name.
        helpful_votes:
          type: integer
          description: Number of shoppers who marked the review as helpful.
        variant:
          type: string
          description: Variant the buyer bought, such as its color and size.
        sku_id:
          type: string
          description: AliExpress SKU ID of the variant bought.
        shipping_method:
          type: string
          description: Shipping method of the order.
        images:
          type: array
          description: Photos the buyer attached.
          items:
            $ref: '#/components/schemas/Image'
        aspects:
          type: array
          description: Aspects of the product the buyer rated.
          items:
            $ref: '#/components/schemas/Aspect'
        response:
          $ref: '#/components/schemas/Response'
        additional_review:
          $ref: '#/components/schemas/AdditionalReview'
    User:
      type: object
      properties:
        name:
          type: string
          description: Reviewer name as AliExpress shows it, usually masked.
        country:
          type: string
          description: Two-letter code of the reviewer's country.
        avatar:
          type: string
          description: Reviewer profile picture.
    Image:
      type: object
      required: [link]
      properties:
        link:
          type: string
          description: Full-size photo.
        thumbnail:
          type: string
          description: Thumbnail of the photo.
    Aspect:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Aspect rated, such as durability.
        value:
          type: string
          description: Rating the buyer gave the aspect.
    Response:
      type: object
      required: [text]
      properties:
        text:
          type: string
          description: Seller's response in the requested language.
        original_text:
          type: string
          description: Seller's response as written, when it differs from `text`.
    AdditionalReview:
      type: object
      properties:
        date:
          type: string
          description: Date of the additional review, as AliExpress writes it.
        text:
          type: string
          description: Additional review text in the requested language.
        original_text:
          type: string
          description: Additional review text as the buyer wrote it, when it differs from `text`.
        images:
          type: array
          description: Photos the buyer attached to the additional review.
          items:
            $ref: '#/components/schemas/Image'
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page.
        next:
          type: integer
          description: Next page.
        total_pages:
          type: integer
          description: Number of pages AliExpress serves for the rating or filter.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
