Search API

Empower your application with the Search API, a robust tool designed to seamlessly integrate with your platform and deliver a comprehensive search experience. This API enables you to effortlessly implement various search-related functionalities, offering a tailored response to user queries by presenting a curated list of products that align with specific search criteria.

Key Features:

Search Results: Retrieve a dynamic list of products that closely match the user's search query.
Facets and Filters: Enhance the search experience by providing relevant facets and filters, enabling users to refine their search based on specific attributes.
Pagination: Implement pagination options for large result sets, ensuring smooth navigation through search results.
Sorting Options: Customize the presentation of search results with sorting options tailored to your application's requirements.
Spell Check Suggestions: Improve user engagement by offering spell check suggestions, enhancing the accuracy of search queries.

Search Endpoint

Endpoint

POST: http://example.com/v1/search/{app_id}/query

Sample Request

curl -X 'POST' \
  'https://*****.topiq.ai/v1/search/{{app_id}}/query' \
  -H 'accept: application/json' \
  -H 'Authorization: {{api_key}}' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "shoes"
}'

Authentication

Ensure that you include an HTTP Bearer token in the headers of each request to authenticate. For more details please check Service Accounts.

Error Codes

404 (Not Found): Indicates the requested resource doesn’t exist. In the browser, this means the URL is not recognized. In an API, this can also mean that the endpoint is valid but the resource itself does not exist.
400 (Bad Request): Indicates the request was unacceptable, often due to missing a required parameter.
401 (Unauthorized): No valid API key provided.
200 (Ok): Indicates that everything worked as expected.

Request Parameters

The values of the request parameters are defined below:

Attribute Name	Data Type	Description	Possible Values/Format
query	String	Query passed from the user	"television"
appId	String	Application ID	"3e6be2d7-5ba8-45f3-9abc-9e27f14e0e01"
explicitFilters	Array	Filters applied by the user.	Array of filter objects
explicitFilters.type	String	Type of filter (Term or Range)	"term" or "range"
explicitFilters.field_name	String	Name of the field to which the filter is applied.	"category"
explicitFilters.required	Boolean	Indicates whether the filter is required.	true or false
explicitFilters.values	Array	List of values for the filter.	Array of values
sortedBy	Array	Order in which the response should be sorted.	Array of sorting configurations
pagination	Object	Specifies the page and page size for pagination.	Object with "page" and "pageSize"
grouping	Object	Grouping options for documents.	Object with "groupingField", "sortableField", "enable"
grouping.groupingField	String	Field used for grouping.	"category"
grouping.sortableField	String	Field used for sorting within groups.	"price"
grouping.enable	Boolean	Indicates whether grouping is enabled.	true or false
channelName	String	Channel name, either "WEB" or "MOBILE".	"WEB"
spellOpt	String	Spell correction option.	"default", "in", "out"
aggregateResults	Boolean	Flag to enable/disable facets (aggregate results).	true or false

Response Components

Search API returns the list of products that match the search criteria. The response would be in application/JSON content type format.

Attribute Name	Description
status	The overall status of the search response, indicating whether the request was successful.
statusCode	The HTTP status code returned in the response.
data	An array containing detailed information about the product(s) matching the search criteria.
meta	Additional metadata providing insights into the search and facets.
meta.queries	An array of search queries used in the request.
meta.facets	Detailed information about facets (filters) applied to the search.
meta.facets.label	The label or identifier of the facet.
meta.facets.displayName	The display name of the facet.
meta.facets.facetType	The type of facet, such as "GLOBAL".
meta.facets.values	An array of values within the facet, each containing information like label, count, and popularity.
meta.sortedBy	Sorting configurations applied to the search results.
meta.sortedBy.field	The field based on which sorting is applied.
meta.sortedBy.isApplied	Indicates whether the sorting is applied.
meta.sortedBy.sortOrder	The order of sorting, for example, "ASCENDING".
meta.sortedBy.displayName	The display name of the sorting configuration.
meta.pagination	Information about pagination, including the current page, page size, total products, and total pages.
meta.spellOpt	The spell correction option used in the search.
meta.hits	The number of products that match the search criteria.
meta.searchFallback	Indicates whether a fallback mechanism was triggered in the search.
meta.rulesApplied	Indicates whether any rules were applied to the search results.

Querying

The query parameter in the search API defines the search query entered by a visitor in your application. This process is commonly known as querying, and the query parameter is essential for retrieving relevant search results.

For example, if a visitor searches for "speaker," the corresponding API call would include the query payload like this:

curl -X 'POST' \
  'https://*****.topiq.ai/v1/search/{{app_id}}/query' \
  -H 'accept: application/json' \
  -H 'Authorization: {{api_key}}' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "speaker"
}'

Sample Json Response

{
  "status": "OK",
  "statusCode": 200,
  "data": [
    {
      "Name": "JBL Flip 5 20W Portable Bluetooth Speaker (IPX7 Water Resistant, JBL's Signature Sound, Stereo Channel, Black)",
    }
  ],
  "meta": {
    "queries": [
      "speaker"
    ],
    "facets": [
      
    ],
    "sortedBy": [
      {
        "field": "MOP",
        "isApplied": false,
        "sortOrder": "ASCENDING",
        "configuredSorts": null,
        "displayName": "Price (Lowest First)"
      }
    ],
    "pagination": {
      "page": 0,
      "pageSize": 1,
      "totalProducts": 588,
      "totalPages": 588
    },
    "spellOpt": "DEFAULT",
    "hits": 1,
    "searchFallback": false,
    "rulesApplied": true
  },
}

Pagination

To customize the pagination in the search API, you can utilize the "pagination" parameter in your API request. This parameter empowers you to manage the number of results returned and the starting point for the results.

In your updated example request:

{
  "query": "speaker",
  "pagination": {
    "page": 0,
    "pageSize": 10
  }
}

The "page" attribute is set to 0, indicating that you are requesting the first page of results.
The "pageSize" attribute is set to 10, specifying that you want ten results per page.

This configuration retrieves the first page of search results with a limit of ten products. For subsequent pages, you can increment the "page" attribute in your API request while maintaining the desired "pageSize" value.

Customizing these parameters allows you to tailor the pagination to your application's requirements, efficiently handling the presentation of search results.

Sorting

To refine the order in which search results are presented, you can leverage the "sort" parameter in the search API. In provided example request:

{
  "query": "speaker",
  "sort": {
    "sortBy": ["MOP,asc"]
  }
}

The "sortBy" attribute is set to ["MOP,asc"], indicating that the search results should be sorted based on the "MOP" (Maximum Orderable Price) field in ascending order.

This configuration ensures that the retrieved products are arranged by their Maximum Orderable Price from the lowest to the highest. You can customize the "sortBy" attribute with other fields and sorting orders, such as ["fieldName,order"], to tailor the sorting logic according to your application's needs.

Implementing sorting in your search API requests provides flexibility in presenting search results, enhancing the user experience by delivering relevant and ordered product listings.

Grouping

The grouping of products with shared attributes, often referred to as "bucketing," enables the organization of search results into distinct groups based on specific field values. This functionality is valuable for presenting top products within each group, along with the most relevant groups themselves. It is crucial to note that the chosen field for bucketing should also serve as a facet field in your e-commerce store.

In this context, users searching for the "iPhone 14" will receive results organized into distinct color groups. Each color group showcases different variants of the iPhone 14, allowing users to easily compare prices and make informed decisions.

{
  "query": "iPhone 14",
  "grouping": {
    "groupingField": "color",
    "sortableField": "price",
    "enable": true
  }
}

groupingField: For organizing iPhones by color, set the grouping field to "color."
sortableField: Choose a field for sorting within each color group. For instance, sorting iPhones within each color group based on their prices can be achieved by setting "sortableField" to "price."
enable: Enable grouping by setting this boolean flag to true.

The API response will present a structured view of iPhone 14 variants, grouped by color, and sorted by price within each color category. This approach simplifies product exploration, offering users a seamless way to navigate through different iPhone 14 options based on their preferred colors.

Facets Overview

Faceting enhances the search experience by empowering shoppers to refine and narrow down their search results effortlessly. When users interact with facets, they can selectively choose filter values to tailor the displayed items to their preferences. Each click on a facet value further refines the search, limiting the results to items that match the selected criteria.

The configuration of facets is a straightforward task accessible through the Console's Configure section. Here, administrators can easily set up and customize facets to align with the specific attributes and filters relevant to their product catalog.

Sample Request

{
  "query": "speaker",
  "explicitFilters": [
    {
      "field_name": "Brand",
      "required": true,
      "type": "term",
      "values": ["JBL"]
    }
  ]
}

In the provided search request, the user is looking for "speakers" with a specific focus on the "JBL" brand. The inclusion of explicit filters allows users to selectively narrow down their search results based on predefined criteria.

Query: The initial search query is "speaker," indicating a broad search for speaker-related products.
Explicit Filters: The facet selected in this case is "Brand," with a requirement flag set to "true." The specified type is "term," indicating that users can filter results by selecting specific values within the "Brand" facet. In this instance, the chosen brand is "JBL."

Sample Response

{
  "status": "OK",
  "statusCode": 200,
  "data": [
  ],
  "meta": {
    "facets": [
      {
        "label": "Brand",
        "displayName": "Brand",
        "facetType": "GLOBAL",
        "scrollable": true,
        "multiSelect": true,
        "expandable": false,
        "searchable": true,
        "maxValuesVisible": 10,
        "values": [
          
          {
            "label": "SAREGAMA",
            "selected": false,
            "count": 49,
            "popular": false
          },
          {
            "label": "JBL",
            "selected": true,
            "count": 37,
            "popular": false
          }
        ],
        "order": 4
      }
    ],
    "sortedBy": [
    ],
    "pagination": {
      "page": 0,
      "pageSize": 1,
      "totalProducts": 37,
      "totalPages": 37
    },
    "spellOpt": "DEFAULT",
    "hits": 1,
    "searchFallback": false,
    "rulesApplied": true
  }
}

Common Features Across Facets

Attribute Name	Description
label	The identifier for the facet, e.g., "Brand".
displayName	The human-readable name for the facet, e.g., "Brand".
facetType	The type of facet, e.g., "GLOBAL".
scrollable	Indicates if the facet values are scrollable (true/false).
multiSelect	Indicates if multiple values can be selected (true/false).
expandable	Indicates if the facet values can be expanded (true/false).
searchable	Indicates if the facet is searchable (true/false).
maxValuesVisible	Maximum number of facet values visible (10 for unlimited).
values	List of facet values with details like label, selected status, count, and popularity.
values.label	The value of the facet, e.g., "SAREGAMA".
values.selected	Indicates if the facet value is selected (true/false).
values.count	The count or number of products associated with the facet value.
values.popular	Indicates if the facet value is marked as popular (true/false). (Depending on the user interaction data).
order	The order or priority of the facet.