openapi: 3.0.0
info:
  title: Lazada Product API
  description: |
    Get one Lazada product from its storefronts in Malaysia, Singapore, Thailand, the Philippines, Vietnam and Indonesia.

    The response carries the product's title, brand, categories, rating, price, images, specifications, every variant with its options, price and stock, the delivery options and their dates, the return and warranty terms, the promotions and the seller. Prices are the ones the product page shows, after any voucher Lazada applies there, in the storefront's currency as text and as numbers.

    Take `product_id` and `sku_id` from Lazada Search results. Send a variant's `sku_id` back to this API for that variant's price, images and delivery, and a category's `category_id` to Lazada Search to search in that category.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Lazada Product
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `lazada_product`'
          schema:
            type: string
            enum: ["lazada_product"]
        - name: product_id
          in: query
          required: true
          description: Lazada product id, a `product_id` from Lazada Search results or the number after `-i` in a product link, such as `478560640`. An id Lazada has no product for on the storefront returns an error.
          schema:
            type: string
            pattern: '^[1-9]\d{0,19}$'
        - name: sku_id
          in: query
          required: false
          description: Variant to describe, a `sku_id` from Lazada Search results or from the `variants` of an earlier response. Without it, the response describes the variant Lazada's product page opens on. A `sku_id` the product does not have returns an error.
          schema:
            type: string
            pattern: '^[1-9]\d{0,19}$'
        - name: lazada_domain
          in: query
          required: false
          description: Lazada storefront to read the product from. It sets the currency and the prices.
          schema:
            type: string
            enum: ["lazada.com.my", "lazada.sg", "lazada.co.th", "lazada.com.ph", "lazada.vn", "lazada.co.id"]
            default: "lazada.com.my"
        - name: language
          in: query
          required: false
          description: Language of Lazada's labels and specifications, and of the title where Lazada translates it. Each storefront takes its own languages, `en`, `ms` or `zh` for Malaysia, `en` or `zh` for Singapore, `th` or `en` for Thailand, `en` for the Philippines, `vi` or `en` for Vietnam and `id` or `en` for Indonesia. The description stays as the seller wrote it. Without it, the response is in English.
          schema:
            type: string
            enum: ["en", "ms", "zh", "th", "vi", "id"]
      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'
        product:
          $ref: '#/components/schemas/Product'
        error:
          type: string
          description: Why the response has no product.
    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: "Lazada product page for this product"
        html_url:
          type: string
          description: "URL to view the raw results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Search engine used
        product_id:
          type: string
          description: Lazada product id asked for
        lazada_domain:
          type: string
          description: Lazada storefront the product was read from
        sku_id:
          type: string
          description: Variant asked for
        language:
          type: string
          description: Language asked for
    Product:
      type: object
      required: [product_id, sku_id]
      properties:
        product_id:
          type: string
          description: Lazada product id.
        sku_id:
          type: string
          description: Id of the variant this response describes.
        title:
          type: string
          description: Product title.
        link:
          type: string
          description: Product page on Lazada, opened on the variant this response describes.
        brand:
          type: string
          description: Brand name.
        categories:
          type: array
          description: Categories the product sits in, from the broadest to the narrowest.
          items:
            $ref: '#/components/schemas/Category'
        rating:
          type: number
          description: Average rating out of 5.
        reviews:
          type: integer
          description: Number of ratings the average is based on.
        reviews_histogram:
          $ref: '#/components/schemas/ReviewsHistogram'
        price:
          type: string
          description: Price of the variant as the product page shows it, after any voucher Lazada applies.
        extracted_price:
          type: number
          description: Numeric price of the variant, after any voucher Lazada applies.
        original_price:
          type: string
          description: Price of the variant before the discount, as Lazada shows it.
        extracted_original_price:
          type: number
          description: Numeric price of the variant before the discount.
        discount_percentage:
          type: integer
          description: Discount on the variant in percent.
        currency:
          type: string
          description: ISO 4217 code of the storefront's currency.
        is_lazmall:
          type: boolean
          description: Whether the product carries the LazMall badge.
        is_out_of_stock:
          type: boolean
          description: Whether the variant is out of stock.
        is_pre_order:
          type: boolean
          description: Whether the variant is sold on pre-order.
        max_quantity:
          type: integer
          description: Largest quantity of the variant Lazada lets a buyer order at once.
        highlights:
          type: array
          description: Key points the seller lists for the product.
          items:
            type: string
        description:
          type: string
          description: Product description as plain text.
        whats_in_the_box:
          type: array
          description: Items in the box, as the seller lists them.
          items:
            type: string
        specifications:
          type: array
          description: Product specifications, such as the brand and the model.
          items:
            $ref: '#/components/schemas/Specification'
        main_image:
          type: string
          description: First image of the variant.
        images:
          type: array
          description: Images of the variant.
          items:
            type: string
        videos:
          type: array
          description: Product videos.
          items:
            $ref: '#/components/schemas/Video'
        variants:
          type: array
          description: Every variant of the product, with its options, price and stock.
          items:
            $ref: '#/components/schemas/Variant'
        delivery_location:
          type: string
          description: Place Lazada quotes the delivery options for, the storefront's default.
        delivery_options:
          type: array
          description: Ways Lazada delivers the variant, with their fees and dates.
          items:
            $ref: '#/components/schemas/DeliveryOption'
        services:
          type: array
          description: Payment and delivery services Lazada lists for the variant, such as cash on delivery.
          items:
            $ref: '#/components/schemas/Term'
        return_and_warranty:
          type: array
          description: Return and warranty terms Lazada lists for the variant.
          items:
            $ref: '#/components/schemas/Term'
        promotions:
          type: array
          description: Vouchers and multi-buy offers on the variant.
          items:
            $ref: '#/components/schemas/Promotion'
        seller:
          $ref: '#/components/schemas/Seller'
    Category:
      type: object
      required: [link]
      properties:
        title:
          type: string
          description: Category name.
        category_id:
          type: string
          description: Code to send in Lazada Search's `category_id` to search in the category.
        link:
          type: string
          description: Category page on Lazada.
    ReviewsHistogram:
      type: object
      description: Number of ratings for each star count, from 5 down to 1.
      required: ["5", "4", "3", "2", "1"]
      properties:
        "5":
          type: integer
          description: Number of 5-star ratings.
        "4":
          type: integer
          description: Number of 4-star ratings.
        "3":
          type: integer
          description: Number of 3-star ratings.
        "2":
          type: integer
          description: Number of 2-star ratings.
        "1":
          type: integer
          description: Number of 1-star ratings.
    Specification:
      type: object
      required: [name, value]
      properties:
        name:
          type: string
          description: Specification name.
        value:
          type: string
          description: Specification value.
    Video:
      type: object
      properties:
        id:
          type: string
          description: Lazada video id.
        link:
          type: string
          description: Link to the video file.
        thumbnail:
          type: string
          description: Video thumbnail.
    Variant:
      type: object
      properties:
        sku_id:
          type: string
          description: Variant id, to send in `sku_id`.
        attributes:
          type: array
          description: Options that make up the variant, such as its color and size.
          items:
            $ref: '#/components/schemas/Attribute'
        price:
          type: string
          description: Price as the product page shows it, after any voucher Lazada applies.
        extracted_price:
          type: number
          description: Numeric price, after any voucher Lazada applies.
        original_price:
          type: string
          description: Price before the discount, as Lazada shows it.
        extracted_original_price:
          type: number
          description: Numeric price before the discount.
        discount_percentage:
          type: integer
          description: Discount in percent.
        thumbnail:
          type: string
          description: Variant image.
        link:
          type: string
          description: Variant page on Lazada.
        is_out_of_stock:
          type: boolean
          description: Whether the variant is out of stock.
        max_quantity:
          type: integer
          description: Largest quantity of the variant Lazada lets a buyer order at once.
    Attribute:
      type: object
      required: [name, value]
      properties:
        name:
          type: string
          description: Option name, such as "Color Family".
        value:
          type: string
          description: Option value, such as "Black" or "EU 40".
    DeliveryOption:
      type: object
      properties:
        type:
          type: string
          description: Delivery type code, such as `standard`.
        title:
          type: string
          description: Delivery option name.
        fee:
          type: string
          description: Delivery fee as Lazada shows it.
        extracted_fee:
          type: number
          description: Numeric delivery fee.
        estimated_delivery:
          type: string
          description: Delivery estimate as Lazada shows it.
        estimated_delivery_from:
          type: string
          format: date
          description: Earliest delivery date.
        estimated_delivery_to:
          type: string
          format: date
          description: Latest delivery date.
        promotion:
          type: string
          description: Delivery offer Lazada shows with the option.
    Term:
      type: object
      properties:
        type:
          type: string
          description: Lazada's code for the term, such as `cod` or `return_policy7`.
        title:
          type: string
          description: Term as Lazada shows it.
    Promotion:
      type: object
      properties:
        type:
          type: string
          description: Promotion kind, such as `voucher` or `multi_buy`.
        title:
          type: string
          description: Promotion as Lazada shows it.
        description:
          type: string
          description: Promotion terms, such as the minimum spend.
    Seller:
      type: object
      description: Seller of the product.
      properties:
        id:
          type: string
          description: Lazada seller id.
        name:
          type: string
          description: Seller name.
        link:
          type: string
          description: Seller's store page on Lazada.
        logo:
          type: string
          description: Store logo.
        positive_ratings_percentage:
          type: integer
          description: Share of positive seller ratings, in percent.
        is_new_seller:
          type: boolean
          description: Whether Lazada marks the seller as new.
        badges:
          type: array
          description: Labels Lazada shows for the store, such as its units sold or its rank in a category.
          items:
            type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
