openapi: 3.0.0
info:
  title: Lazada Search API
  description: |
    Search Lazada's storefronts in Malaysia, Singapore, Thailand, the Philippines, Vietnam and Indonesia for products.

    Each result carries its Lazada product id, title, link, image, price, discount, rating, units sold, seller, brand and where it ships from. Prices are in the storefront's currency, as Lazada shows them and as numbers.

    The response lists the filters Lazada offers for the search. Send an option's `filter_value` in `filters`, or its `category_id` in `category_id`, to narrow the next search.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Lazada Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `lazada_search`'
          schema:
            type: string
            enum: ["lazada_search"]
        - name: q
          in: query
          required: true
          description: Search text, up to 500 characters. Lazada refuses some text, such as script tags, and the search then returns an error.
          schema:
            type: string
            maxLength: 500
        - name: lazada_domain
          in: query
          required: false
          description: Lazada storefront to search. It sets the products, 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 place names. 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. Product titles stay as the seller wrote them.
          schema:
            type: string
            enum: ["en", "ms", "zh", "th", "vi", "id"]
        - name: category_id
          in: query
          required: false
          description: Category to search in, a `category_id` from the `filters` of an earlier response, such as `shop-mens-sneakers`. A category Lazada has no page for returns an error.
          schema:
            type: string
            maxLength: 200
        - name: filters
          in: query
          required: false
          description: Filters to apply, comma-separated, each a `filter_value` from the `filters` of an earlier response, such as `service:official,location:Local`. Several values of one filter widen the results, except Service & Promotion values, which all apply. Values of different filters narrow the results. One brand at a time, up to 20 values. A brand Lazada has no page for returns an error.
          schema:
            type: string
        - name: sort_by
          in: query
          required: false
          description: Sorts the results. `best_selling` puts the products with the most units sold first.
          schema:
            type: string
            enum: ["best_match", "price_low_to_high", "price_high_to_low", "best_selling"]
            default: "best_match"
        - name: price_min
          in: query
          required: false
          description: Lowest price, in the storefront's currency.
          schema:
            type: number
            minimum: 0
            maximum: 1000000000
        - name: price_max
          in: query
          required: false
          description: Highest price, in the storefront's currency. It must not be lower than `price_min`.
          schema:
            type: number
            minimum: 0
            maximum: 1000000000
        - name: rating
          in: query
          required: false
          description: Lowest product rating, in stars.
          schema:
            type: integer
            minimum: 1
            maximum: 5
        - name: page
          in: query
          required: false
          description: Page of results. Lazada lists up to 40 products a page, and some searches get fewer on their first page. The last page is the one whose `pagination` has no `next`.
          schema:
            type: integer
            minimum: 1
            maximum: 102
            default: 1
      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'
        featured_store:
          $ref: '#/components/schemas/FeaturedStore'
        organic_results:
          type: array
          description: Products Lazada lists for the search, in Lazada's order.
          items:
            $ref: '#/components/schemas/OrganicResult'
        filters:
          type: array
          description: Filters Lazada offers for the search.
          items:
            $ref: '#/components/schemas/Filter'
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Why the search returned 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: "Lazada search page for this search"
        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
        q:
          type: string
          description: The text searched for
        lazada_domain:
          type: string
          description: Lazada storefront searched
        language:
          type: string
          description: Language of the results
        category_id:
          type: string
          description: Category searched in
        filters:
          type: string
          description: Filters applied
        sort_by:
          type: string
          description: Sort order
        price_min:
          type: string
          description: Lowest price
        price_max:
          type: string
          description: Highest price
        rating:
          type: string
          description: Lowest product rating
        page:
          type: integer
          description: Page of results
    SearchInformation:
      type: object
      properties:
        query_displayed:
          type: string
          description: Search text as Lazada read it.
        total_results:
          type: integer
          description: Number of products Lazada reports for the search.
        currency:
          type: string
          description: ISO 4217 code of the storefront's currency.
        has_few_relevant_results:
          type: boolean
          description: Whether Lazada reports that few products match the search.
    FeaturedStore:
      type: object
      description: Lazada store shown above the results of a brand search.
      properties:
        name:
          type: string
          description: Store name.
        link:
          type: string
          description: Store page on Lazada.
        logo:
          type: string
          description: Store logo.
    OrganicResult:
      type: object
      required: [position, product_id]
      properties:
        position:
          type: integer
          description: Position of the product on this page of results.
        product_id:
          type: string
          description: Lazada product id, the number in the product link.
        sku_id:
          type: string
          description: Id of the product variant the result shows.
        title:
          type: string
          description: Product title.
        link:
          type: string
          description: Product page on Lazada.
        price:
          type: string
          description: Price as Lazada shows it.
        extracted_price:
          type: number
          description: Numeric price.
        extracted_original_price:
          type: number
          description: Numeric price before the discount.
        discount_percentage:
          type: integer
          description: Discount in percent.
        rating:
          type: number
          description: Average rating out of 5.
        reviews:
          type: integer
          description: Number of ratings the average is based on.
        items_sold:
          type: string
          description: Units sold as Lazada shows them, such as "1.2K sold".
        extracted_items_sold:
          type: integer
          description: Exact number of units sold.
        ships_from:
          type: string
          description: Where the product ships from, such as a state or a country.
        seller:
          type: object
          description: Seller of the product.
          properties:
            id:
              type: string
              description: Lazada seller id.
            name:
              type: string
              description: Seller name.
        brand:
          type: string
          description: Brand name, "No Brand" for unbranded products.
        is_lazmall:
          type: boolean
          description: Whether the product carries the LazMall badge.
        is_free_shipping:
          type: boolean
          description: Whether the product carries a free shipping badge.
        badges:
          type: array
          description: Promotion labels Lazada shows on the product, such as vouchers and savings.
          items:
            type: string
        highlights:
          type: array
          description: Key points the seller lists for the product.
          items:
            type: string
        thumbnail:
          type: string
          description: Product image.
    Filter:
      type: object
      required: [options]
      properties:
        type:
          type: string
          description: Filter name, such as "Category" or "Shipped From".
        options:
          type: array
          description: Choices the filter offers.
          items:
            $ref: '#/components/schemas/FilterOption'
    FilterOption:
      type: object
      properties:
        text:
          type: string
          description: Choice as Lazada shows it.
        filter_value:
          type: string
          description: Code to send in `filters` to apply the choice.
        category_id:
          type: string
          description: Code to send in `category_id` to search in the category.
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page.
        next:
          type: string
          description: Lazada search page with the next products.
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
