Search Suggestions Documentation

---

Overview

The get_search_suggestions function in the ProductListViewSet is responsible for providing intelligent and context-aware search results based on user input. It employs similarity matching to find relevant results from three primary data sources:

1. Parent Categories: Top-level categories.
2. Subcategories: Child categories belonging to parent categories.
3. Products: Active products matching the query.

Endpoint

• URL: /api/v1/catalog/product/list/?query=<search_query>
• Method: GET
• Permission Required: AllowAny

Query Parameters

• query: The search term entered by the user (e.g., Blue Kurtha).

Usage

This endpoint is part of a product listing API, designed to offer quick and meaningful search suggestions. Users can access the endpoint with a query string to retrieve relevant suggestions grouped by category and product type.

How it Works

The function uses TrigramSimilarity from Django to calculate similarity scores for records in the Category and Product models. Results are filtered based on a similarity threshold and grouped into structured response types.

Key Steps

1. Retrieve and Annotate Data:
2. Fetch parent categories, subcategories, and products, annotating each with a similarity score.

3. Apply a threshold to exclude irrelevant matches (similarity > 0.1).

4. Organize Results:

5. Group results into three categories:

   • Category (Parent Categories)
   • Sub-Category (Child Categories)
   • Product (Matching Products)

6. Format and Return Data:

7. Structure the data in a user-friendly JSON format with fields like id, name, slug, and associated media (images, videos).
8. Return results grouped by their type.

---

Response Format

The response is an array of suggestions grouped by type. Each group contains relevant results for that type.

Example Response

[
  {
    "type": "Category",
    "result": [
      {
        "id": 1,
        "name": "Clothing",
        "banner_image": "https://example.com/images/clothing_banner.jpg",
        "thumbnail_image": "https://example.com/images/clothing_thumb.jpg"
      }
    ]
  },
  {
    "type": "Sub-Category",
    "result": [
      {
        "id": 2,
        "name": "Men's Wear",
        "banner_image": "https://example.com/images/menswear_banner.jpg",
        "thumbnail_image": "https://example.com/images/menswear_thumb.jpg",
        "child_categories": [
          {
            "id": 3,
            "name": "Formal Wear",
            "slug": "formal-wear",
            "description": "Elegant and professional attire",
            "banner_image": "https://example.com/images/formalwear_banner.jpg",
            "thumbnail_image": "https://example.com/images/formalwear_thumb.jpg"
          }
        ]
      }
    ]
  },
  {
    "type": "Product",
    "result": [
      {
        "id": 101,
        "name": "Blue Kurtha",
        "slug": "blue-kurtha",
        "vendor": 5,
        "price": "49.99",
        "discount_percent": "10",
        "description": "A stylish and comfortable kurtha.",
        "is_featured": true,
        "is_active": true,
        "video": "https://example.com/videos/blue_kurtha.mp4",
        "parent_category": {
          "id": 1,
          "name": "Clothing",
          "slug": "clothing",
          "description": "All types of clothing",
          "banner_image": "https://example.com/images/clothing_banner.jpg",
          "thumbnail_image": "https://example.com/images/clothing_thumb.jpg"
        },
        "brand": "Ethnic Styles"
      }
    ]
  }
]

Implementation Details

Functionality

• Parent Categories: Retrieves and ranks top-level categories based on similarity scores.

• Subcategories: Fetches child categories, including their parent category information, to provide contextual results.

• Products: Matches active products with the query, including their details and associated parent categories.

Dependencies

• TrigramSimilarity: Used for similarity scoring in the query.
• Django ORM: To filter and annotate querysets.
• Response: For sending the structured response.

Edge Cases

• If no results match the query, an empty list is returned for each type.
• Handles missing media fields by returning null.
• Supports hierarchical category structures with nested child categories.

Conclusion

The get_search_suggestions function enhances the user experience by offering contextually relevant search results. It integrates seamlessly with the product listing API and supports dynamic filtering and sorting based on user input.

Example Request

URL:

/api/v1/catalog/product/list/?query=Blue%20Kurtha

Method: GET

Example Use Case

• A user enters Blue Kurtha as the search term to find products matching the name, description, or related categories. The endpoint returns suggestions grouped into categories, subcategories, and product results, enabling the user to quickly find what they are looking for.

---