Search

Product search and discovery

Search products with faceted filtering

get

Performs a full-text search across products with support for faceted filtering, sorting, and pagination. Returns matching products along with available filter facets and sorting options.

How Search Works:

When a search request is received, the system first checks if the same search with identical parameters has been performed recently. If found in cache, results are returned immediately.

If no cached result is found, the search process begins. The system queries Elasticsearch, which stores product metadata (not full product data). The fields used for querying include: in_stock, price, basket_offer_ids, category_ids, and collection_ids.

Product Extraction Strategies:

After receiving results from Elasticsearch, products are extracted using one of the following strategies:

• DefaultProductExtractionStrategy: Returns all product IDs that matched the search

• FirstItemSearchExtractionStrategy: Returns the first sub-product from each meta product

• ListableFirstProductExtractionStrategy: Returns listable products when meta products contain sub-products

• MinPriceFirstProductExtractionStrategy: Returns sub-products sorted by minimum price in ascending order

• MaxPriceFirstProductExtractionStrategy: Returns sub-products sorted by maximum price in ascending order

• AllSubProductsExtractionStrategy: Returns all sub-product IDs belonging to meta products

Product and Facet Conversion:

After extraction, two conversion processes occur:

1. Product Conversion: Product IDs from Elasticsearch are fetched from the database in the order they were returned, maintaining search relevance ordering

2. Facet Conversion: Facet data (filterable attribute IDs) is used to fetch attribute values from the database and create filter widgets. Widget types are determined by FacetConfiguration database records:

   • If a Facet Configuration exists for the attribute, it specifies the widget type, aggregation settings, and display options

   • If no Facet Configuration exists, fallback rules apply:

     • category_ids uses Category Widget

     • basket_offer_ids uses Promotion Widget

     • All other attributes default to Multi Select Widget

   • Widget configurations support translation for multi-language sites

   • Widgets include choices with quantities, labels, selection states, and URLs for filtering

Filtering Support:

The search supports filtering by various attributes including:

• Stock availability (in_stock)

• Price ranges (price)

• Categories (category_ids)

• Collections (collection_ids)

• Sellers (seller_ids)

• Basket offers (basket_offer_ids)

• Discount amounts and ratios (discount_amount, discount_ratio)

• Category paths (category_paths)

• Custom product attributes (attributes_*)

• Custom fields (custom_*)

Pagination and Sorting:

Results are paginated and can be sorted using available sort options. The default page size is configurable via the SEARCH_DEFAULT_PAGE_SIZE dynamic setting and can be overridden via the page_size parameter. Maximum page size is limited to 250 items.

Sort options are configured through the SortOption database model and managed via the administration interface. Each sort option defines:

• Display label (translatable)

• Parameter value used in the sorter query parameter

• Elasticsearch sort configuration (field paths, directions, nested queries)

• Display order and visibility settings

When a sort option is selected, its Elasticsearch configuration is applied to the search query. Sort options automatically adapt to inventory strategy context, adjusting price field references when multiple price lists are active. A secondary sort by product listing ID ensures consistent ordering across pages.

Fuzzy Search:

When fuzzy search is enabled (SEARCH_FUZZY_SEARCH_ACTIVE) and the query is longer than 4 characters, the search includes approximate matches with typo tolerance (fuzziness level: 1).

Query parameters

search_textstringOptional

Search query text

Example: {"value":"smartwatch","summary":"Single word search"}

pageinteger · min: 1Optional

Page number (1-indexed)

Example: {"value":1,"summary":"First page"}

page_sizeinteger · min: 1 · max: 250Optional

Number of results per page. Maximum value is 250. If not specified, the default page size from SEARCH_DEFAULT_PAGE_SIZE dynamic setting is used.

Example: {"value":20,"summary":"Standard page size"}

sorterstringOptional

Sort option value

Example: {"value":"default","summary":"Default sorting"}

default_page_sizeinteger · min: 1 · max: 250Optional

Default page size for pagination. This value is used when page_size parameter is not provided. The actual page size will be the minimum of this value and the maximum allowed page size (250). If not provided, uses the SEARCH_DEFAULT_PAGE_SIZE dynamic setting value

Example: 20

elasticsearch_valuestringOptional

Custom Elasticsearch sort value to override or extend the default sorting behavior. When provided, this value is prepended to the selected sorter's Elasticsearch value. Can be a single value or comma-separated list of values. Used for advanced sorting customization in Elasticsearch queries

Example: _score

extraction_strategystringOptional

Product extraction strategy class path. Determines how products are extracted from Elasticsearch results, especially when dealing with meta products and sub-products. If not provided, uses the value from SEARCH_PRODUCT_EXTRACTION_STRATEGY dynamic setting, or defaults to DefaultProductExtractionStrategy. Available strategies:

• DefaultProductExtractionStrategy: Returns all matching product IDs
• FirstItemSearchExtractionStrategy: Returns first sub-product from each meta product
• ListableFirstProductExtractionStrategy: Returns listable products when meta products contain sub-products
• MinPriceFirstProductExtractionStrategy: Returns sub-products sorted by minimum price (ascending)
• MaxPriceFirstProductExtractionStrategy: Returns sub-products sorted by maximum price (ascending)
• AllSubProductsExtractionStrategy: Returns all sub-product IDs belonging to meta products

Example: omnishop.search.strategies.DefaultProductExtractionStrategy

inventory_strategyintegerOptional

Inventory strategy identifier. Used in shops with multiple inventory systems to determine which price list should be used. When provided, price fields are prefixed with the price list ID (e.g., price_1234 instead of price). If not provided, uses the basket's inventory strategy or defaults to the standard inventory

Example: 1234

in_stockstring[]Optional

Filter by stock availability (comma-separated values)

Example: {"value":["true"],"summary":"Filter for in-stock products only"}

pricestring[]Optional

Filter by price range (comma-separated values)

Example: {"value":["0","100"],"summary":"Price range from 0 to 100"}

category_idsinteger[]Optional

Filter by category identifiers (comma-separated)

Example: {"value":[14],"summary":"Filter by single category"}

collection_idsinteger[]Optional

Filter by collection identifiers (comma-separated)

Example: {"value":[5],"summary":"Filter by single collection"}

seller_idsinteger[]Optional

Filter by seller/data source identifiers (comma-separated)

basket_offer_idsinteger[]Optional

Filter by basket offer/promotion identifiers (comma-separated)

Example: {"value":[100],"summary":"Filter by single promotion"}

discount_amountstring[]Optional

Filter by discount amount range (comma-separated min, max)

Example: {"value":["0","50"],"summary":"Discount amount from 0 to 50"}

discount_ratiostring[]Optional

Filter by discount ratio range (comma-separated min, max)

Example: {"value":["0","30"],"summary":"Discount ratio from 0% to 30%"}

category_pathsstring[]Optional

Filter by category paths (comma-separated)

Example: {"value":["000100010001"],"summary":"Filter by single category path"}

data_modestring · enumOptional

Data retrieval mode. When set to "facets", only facet data is returned. When set to "products", only product data is returned. When not specified, both facets and products are returned.

Example: {"value":"facets","summary":"Retrieve only facets"}Possible values:

Responses

200

Search results retrieved successfully

application/json

Search results with products, facets, and pagination

search_textstring · nullableRequired

The search query text used, or null if no search text was provided

Example: smartwatch

get

/list/

HTTPcURLJavaScriptPython

GET /list/ HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

200

Search results retrieved successfully

{
  "pagination": {
    "current_page": 1,
    "num_pages": 2,
    "page_size": 24,
    "total_count": 38
  },
  "facets": [
    {
      "name": "Kategori",
      "key": "category_ids",
      "search_key": "category_ids",
      "widget_type": "category",
      "order": 1,
      "extra_params": {},
      "data": {
        "widget_type": "category",
        "name": "Kategori",
        "key": "category_ids",
        "search_key": "category_ids",
        "choices": [
          {
            "label": "new WOMEN",
            "value": 14,
            "quantity": 18,
            "is_selected": false,
            "depth": 0,
            "real_depth": 2,
            "url": "/list/?format=json&category_ids=14",
            "menuitemmodel": "41dad8d486d54936bcd643b30f0e5134",
            "is_parent_of_selection": false
          },
          {
            "label": "root test",
            "value": 465,
            "quantity": 38,
            "is_selected": false,
            "depth": 0,
            "real_depth": 2,
            "url": "/list/?format=json&category_ids=465",
            "menuitemmodel": null,
            "is_parent_of_selection": false
          }
        ],
        "order": 1
      }
    },
    {
      "name": "PRICEEE",
      "key": "price",
      "search_key": "price",
      "widget_type": "range",
      "order": -1,
      "extra_params": {},
      "data": {
        "widget_type": "range",
        "name": "PRICEEE",
        "key": "price",
        "quantity": 31,
        "min_value": 2.03,
        "max_value": 199.04,
        "step": 1,
        "order": -1
      }
    }
  ],
  "sorters": [
    {
      "label": "Default",
      "value": "default",
      "is_selected": true
    },
    {
      "label": "Newcomers",
      "value": "newcomers",
      "is_selected": false
    },
    {
      "label": "Ascending Price",
      "value": "price",
      "is_selected": false
    }
  ],
  "search_text": null,
  "products": [
    {
      "pk": 828,
      "name": "Product 64",
      "sku": "similarity-simple-2",
      "base_code": "similarity-test",
      "attributes": {
        "int_color": "BEAUTY"
      },
      "attribute_set": 2,
      "attributes_kwargs": {
        "int_color": {
          "label": "BEAUTY",
          "value": "BEAUTY",
          "data_type": "dropdown"
        }
      },
      "extra_attributes": {},
      "productimage_set": [
        {
          "pk": 5050,
          "status": "active",
          "image": "https://a7c0d7.cdn.akinoncloud.com/products/2025/09/08/3589/463f482b-f080-4015-8d5d-bbafb963f857.jpg",
          "order": 0,
          "created_date": "2025-09-08T08:24:21.299473Z",
          "specialimage_set": []
        }
      ],
      "price": "199.04",
      "in_stock": true,
      "currency_type": "try",
      "retail_price": "199.04",
      "unit_type": "qty",
      "tax_rate": "0.00",
      "absolute_url": "/product-64/",
      "productvideo_set": [],
      "product_type": "0",
      "price_type": "default",
      "form_schema": null,
      "is_ready_to_basket": true,
      "stock": 999,
      "data_source": null,
      "basket_offers": [
        {
          "pk": 2744,
          "label": "%30 & Max Discount Amount = 999",
          "listing_kwargs": {
            "quantity": 3,
            "discounted_total_price": "199.50",
            "discount": "50.00"
          },
          "kwargs": {
            "show_benefit_products": true
          },
          "client_types": []
        }
      ],
      "extra_data": {
        "variants": [
          {
            "attribute_key": "int_color",
            "options": [
              {
                "label": "BEAUTY",
                "product": {
                  "pk": 828,
                  "sku": "similarity-simple-2",
                  "price": "199",
                  "stock": 1000,
                  "attributes": {
                    "int_color": "BEAUTY"
                  },
                  "retail_price": "299",
                  "price_extra_field": {},
                  "absolute_url": "/product-64/",
                  "productimage_set": []
                },
                "in_stock": true,
                "is_selectable": true
              }
            ]
          }
        ]
      },
      "is_listable": true,
      "listing_code": null,
      "price_extra_field": {},
      "discount_amount": 0,
      "discount_ratio": 0
    }
  ]
}