openapi: 3.0.0
info:
  title: Flipkart Search API
  description: |
    The Flipkart Search API returns the products Flipkart shows for a search on flipkart.com, India's online marketplace. Each result includes the product ID, title, link and image, and when Flipkart shows them, the brand, price in Indian rupees, MRP, discount, rating with its star breakdown, key specs, offer badges, stock state, the F-Assured tag and whether the card is sponsored. The response also includes the filters Flipkart offers for the search, the category path it resolved the query into, and the pages of the results.

    Flipkart shows at most 1,000 results for a search: 24 a page on list layouts and 40 a page on grid layouts. A search Flipkart answers with no products, or a page past the last one, returns an `error` message in place of the results.

    **Cross-linking**: The `filters` parameter accepts the `filter_value` of the values in `filters`. The `category_id` parameter accepts the `category_id` of an entry in `search_information.categories`. The `product_id` of a result identifies the product on Flipkart, and its `link` opens the product page.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: Flipkart Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: Engine to use for the search
          schema:
            type: string
            enum: ["flipkart_search"]
            default: "flipkart_search"
        - name: q
          in: query
          required: true
          description: Search query, such as `iphone 15`. Flipkart searches a misspelled or unknown query as the closest one it knows, and `search_information.is_augmented` then is true.
          schema:
            type: string
        - name: category_id
          in: query
          required: false
          description: Flipkart category path to search in, such as `tyy,4io` for Mobiles. Use the `category_id` of an entry in `search_information.categories`.
          schema:
            type: string
            pattern: '^[a-z0-9]{3}(?:,[a-z0-9]{3})*$'
        - name: sort_by
          in: query
          required: false
          description: Sort order of the results. Flipkart offers `best_discount` on some categories only and sorts by `best_match` where it does not.
          schema:
            type: string
            enum: ["best_match", "popularity", "price_low_to_high", "price_high_to_low", "new_arrivals", "best_discount"]
            default: "best_match"
        - name: price_min
          in: query
          required: false
          description: Minimum price in Indian rupees.
          schema:
            type: number
            minimum: 0
            maximum: 10000000
        - name: price_max
          in: query
          required: false
          description: Maximum price in Indian rupees, at least `price_min`.
          schema:
            type: number
            minimum: 0
            maximum: 10000000
        - name: filters
          in: query
          required: false
          description: 'Filters to apply, as `filter_value` strings from the response''s `filters` joined by `||`, such as `brand:Apple||rating:4★ & above`. Each is a filter `id` and a value name, `id:name`. Two values of one filter return products that match either. Use `price_min` and `price_max` for a price range.'
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Results page number, from 1 to 41. Flipkart shows at most 1,000 results for a search, so a grid layout of 40 products a page ends at page 25.
          schema:
            type: integer
            minimum: 1
            maximum: 41
            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'
        organic_results:
          type: array
          items:
            $ref: '#/components/schemas/OrganicResult'
          description: Products on the results page, sponsored ones included, in the order Flipkart shows them
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
          description: Filters Flipkart offers for the results
        pagination:
          $ref: '#/components/schemas/Pagination'
        error:
          type: string
          description: Error message for a search Flipkart answers with 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: Flipkart URL of the results page
        html_url:
          type: string
          description: URL to view HTML results
        json_url:
          type: string
          description: URL to view JSON results
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: Engine used for the search
        q:
          type: string
          description: Search query
        category_id:
          type: string
          description: Flipkart category path searched in
        sort_by:
          type: string
          description: Sort order applied
        price_min:
          type: string
          description: Minimum price applied, in Indian rupees
        price_max:
          type: string
          description: Maximum price applied, in Indian rupees
        filters:
          type: string
          description: Filters applied
        page:
          type: string
          description: Results page number
    SearchInformation:
      type: object
      required: [query_displayed, total_results]
      properties:
        query_displayed:
          type: string
          description: Search query as Flipkart searched it
        total_results:
          type: integer
          description: Number of products Flipkart reports for the search
        is_augmented:
          type: boolean
          description: Whether Flipkart searched a closer query in place of the one sent
        categories:
          type: array
          items:
            $ref: '#/components/schemas/Category'
          description: Category path Flipkart resolved the query into, from the broadest category to the narrowest
    Category:
      type: object
      required: [name, category_id, link]
      properties:
        name:
          type: string
          description: Category name
        category_id:
          type: string
          description: Flipkart category path, accepted by the `category_id` parameter
        link:
          type: string
          description: URL of the category page on Flipkart
    OrganicResult:
      type: object
      required: [position, product_id, title, link, thumbnail]
      properties:
        position:
          type: integer
          description: Position of the product on the results page, starting at 1
        product_id:
          type: string
          description: Flipkart product ID (FSN)
        listing_id:
          type: string
          description: Flipkart ID of the seller listing the card shows
        item_id:
          type: string
          description: Flipkart ID of the product page, the `itm` part of its link
        title:
          type: string
          description: Product title
        subtitle:
          type: string
          description: Variant line under the title, such as the color and size
        brand:
          type: string
          description: Product brand
        link:
          type: string
          description: URL of the product page on Flipkart
        rating:
          type: number
          description: Average star rating, out of 5
        reviews:
          type: integer
          description: Number of star ratings
        reviews_with_text:
          type: integer
          description: Number of written reviews
        reviews_histogram:
          $ref: '#/components/schemas/ReviewsHistogram'
        price:
          type: string
          description: Selling price as Flipkart shows it, in Indian rupees
        extracted_price:
          type: integer
          description: Selling price in Indian rupees
        original_price:
          type: string
          description: Maximum retail price (MRP) as Flipkart shows it, in Indian rupees
        extracted_original_price:
          type: integer
          description: Maximum retail price (MRP) in Indian rupees
        discount:
          type: integer
          description: Discount off the MRP in Indian rupees
        discount_percentage:
          type: integer
          description: Discount off the MRP as a whole percentage, as Flipkart shows it
        key_specs:
          type: array
          items:
            type: string
          description: Key specifications Flipkart lists on the card
        badges:
          type: array
          items:
            type: string
          description: Tags and offer lines on the card, such as Bestseller or an exchange offer
        warranty:
          type: string
          description: Warranty summary
        is_assured:
          type: boolean
          description: Whether the product carries the F-Assured tag
        is_sponsored:
          type: boolean
          description: Whether the card is a sponsored product
        is_out_of_stock:
          type: boolean
          description: Whether the product cannot be bought now
        availability_state:
          type: string
          description: Flipkart's stock state for the card, such as `in_stock`, `out_of_stock` or `coming_soon`
        thumbnail:
          type: string
          description: URL of the product image
        images:
          type: array
          items:
            type: string
          description: URLs of the card's image gallery at the size Flipkart's product page zooms to
    ReviewsHistogram:
      type: object
      required: [five_star, four_star, three_star, two_star, one_star]
      properties:
        five_star:
          type: integer
          description: Number of 5-star ratings
        four_star:
          type: integer
          description: Number of 4-star ratings
        three_star:
          type: integer
          description: Number of 3-star ratings
        two_star:
          type: integer
          description: Number of 2-star ratings
        one_star:
          type: integer
          description: Number of 1-star ratings
    Filter:
      type: object
      required: [id, type, values]
      properties:
        id:
          type: string
          description: Filter ID, the part before the colon in a `filter_value`
        name:
          type: string
          description: Filter name as Flipkart shows it
        type:
          type: string
          enum: ["checkbox", "range"]
          description: Filter kind, a list of values to tick or the price slider
        values:
          type: array
          items:
            $ref: '#/components/schemas/FilterValue'
          description: Values of the filter, up to the 30 Flipkart lists first plus any applied one, or the price slider's steps
    FilterValue:
      type: object
      required: [name]
      properties:
        name:
          type: string
          description: Value name as Flipkart shows it
        items_count:
          type: integer
          description: Number of products with this value
        is_selected:
          type: boolean
          description: Whether the value is applied to the results
        filter_value:
          type: string
          description: Value for the `filters` parameter that applies this value
        price:
          type: integer
          description: Price step in Indian rupees, for `price_min` or `price_max`
    Pagination:
      type: object
      required: [current]
      properties:
        current:
          type: integer
          description: Current page number
        previous:
          type: string
          description: URL of the previous page on Flipkart
        next:
          type: string
          description: URL of the next page on Flipkart
        other_pages:
          type: object
          additionalProperties:
            type: string
          description: URLs of other pages on Flipkart, keyed by page number
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong
