> ## Documentation Index > Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt > Use this file to discover all available pages before exploring further. # Product Search API Guide > Choose the right product search endpoint and use its query, filter, sort, paging, facet, spell correction, and Merchandizing rule parameters. The storefront Product Search APIs return the products for search results pages and category listing pages, along with the facets shoppers use to narrow those results. This guide explains which endpoint to call, how the main query parameters work, and how to combine them. For the full parameter list, see the [Site Search](https://docs.kibocommerce.com/api-reference/productsearch/site-search.md) and [Search Products](https://docs.kibocommerce.com/api-reference/productsearch/search-products.md) API reference. All examples use this base URL: ``` https://t1000000.sb.usc1.gcp.kibocommerce.com/api/commerce/catalog/storefront/productsearch ``` Examples show query strings without URL encoding so they are easier to read. URL-encode parameter values (spaces, colons, brackets, and the tilde in `tenant~` attribute names) when you send real requests. ## Choose an Endpoint | Endpoint | Returns | Use it for | | - | - | - | | `GET .../siteSearch` | Lightweight items read directly from the search index. Each item contains `productCode` plus any fields you name in `fieldList`. | Search results pages and category listing pages. This is the recommended endpoint for storefront search. | | `GET .../search` | Full storefront `Product` objects (content, price, options, inventory, and so on). | Testing relevancy and personalization scores. Do not use it for production search pages. | | `GET .../suggest2` | Suggested products, categories, and terms. | Type-ahead suggestions as the shopper types. See [Suggest2 API](https://docs.kibocommerce.com/pages/integrating-personalization-with-search.md#suggest2-api). | The two search endpoints accept the same query, filter, sort, paging, facet, and Merchandizing parameters. They differ in what they return and in how page size limits apply (see [Page Size Limits](#page-size-limits)): * `siteSearch` returns only the fields you request, so responses stay small. It uses the keyword search page size limit whether or not you pass `query`. * `search` runs as a keyword search when you pass a `query` value, and as a listing (browse) request when you do not. The page size limit depends on which one it is. ## Core Parameters ### query The shopper's search terms. When `query` is present, Kibo applies your search settings, synonyms, spell correction, and [search term redirects](https://docs.kibocommerce.com/pages/search-term-redirects.md). ``` GET .../siteSearch?query=hiking boots&fieldList=productName,priceL,priceH,productImageUrls ``` If the query matches a search term redirect, the response contains a `searchRedirect` URL and no product results. Send the shopper to that URL. ### filter A filter expression that limits results, using the same operators as other Kibo APIs: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `sw`, `cont`, `in[...]`, `between[...]`, and `and`/`or` with parentheses for grouping. Custom attributes use their fully qualified name, such as `tenant~color`. ``` GET .../siteSearch?query=jacket&filter=categoryCode eq outerwear and price.price lt 200 GET .../siteSearch?query=shirt&filter=locationsInStock in[STORE-01,STORE-02] ``` Escape special characters in filter values with a caret. For the full operator list, escaping rules, and the `locationsInStock` filter, see [Sorting and Filtering APIs](https://docs.kibocommerce.com/pages/sorting-and-filtering-apis.md#filtering) and [Product Storefront Location Filter](https://docs.kibocommerce.com/pages/sorting-and-filtering-apis.md#product-storefront-location-filter). Use `filter` for conditions your page sets (such as the current category). Use [`facetValueFilter`](#apply-a-facet-value) for values the shopper picks from the facet list, so the facet keeps showing the other values the shopper can add. ### sortBy A field name followed by `asc` or `desc`, for example `sortBy=price desc` or `sortBy=createDate desc`. Separate multiple sorts with commas. If you omit `sortBy`, Kibo uses its default ordering, including any Merchandizing rule that applies. Passing `sortBy` turns off Merchandizing rule matching for that request, including a rule you name with `merchandizingRuleCode`. See [Merchandizing Rules](#merchandizing-rules). ### Paging with startIndex and pageSize `startIndex` is the zero-based offset of the first result. `pageSize` is the number of results to return. To show page 3 with 24 products per page: ``` GET .../siteSearch?query=boots&pageSize=24&startIndex=48 ``` The response includes `totalCount`, `startIndex`, `pageSize`, and `pageCount` for building pagination controls. ### Deep paging with cursorMark To walk through a large result set, such as when exporting every product in a category, use `cursorMark` instead of `startIndex`: 1. Send the first request with `cursorMark=*`. 2. Read `nextCursorMark` from the response. 3. Send the same request again with `cursorMark` set to that value. 4. Stop when the response has no `nextCursorMark`. ``` GET .../siteSearch?filter=categoryCode eq outerwear&fieldList=productName&pageSize=200&cursorMark=* GET .../siteSearch?filter=categoryCode eq outerwear&fieldList=productName&pageSize=200&cursorMark={nextCursorMark} ``` Keep every other parameter the same between calls. `cursorMark` works on both `siteSearch` and `search`. ### Page Size Limits | Request | Default `pageSize` | Maximum `pageSize` | Over the maximum | | - | - | - | - | | `siteSearch` | 10 | 10,000 | The request fails with a validation error. | | `search` with a `query` value | 10 | 10,000 | The request fails with a validation error. | | `search` without a `query` value | 10 | 200 | Kibo returns 200 results. No error is returned. | The 10,000 maximum for keyword searches is a tenant setting. Kibo can raise or lower it for your tenant with the `search-sitesearch-pagesize-limit` tenant attribute. Contact Kibo Support to change it. Large pages are slower to build and return. For storefront pages, keep `pageSize` close to the number of products you display. For exports, use `cursorMark` with a moderate page size. ## Facets Facets let shoppers narrow results by category, price, brand, or any attribute that is set up for faceting in the [search schema](https://docs.kibocommerce.com/pages/search-schema-overview.md). The same request that returns products also returns a `facets` array, so you do not need a separate call. Each facet in the response has a `label`, a `field`, a `facetType`, and a `values` array. Each value has a `label`, a `value`, a `count`, an `isApplied` flag, and a `filterValue`. Category facets also include `childrenFacetValues`. ### facetTemplate Loads the facets configured in the Admin for a category (see [Facets](https://docs.kibocommerce.com/pages/facets.md)). The format is `categoryCode:{code}` or `categoryId:{id}`. ``` GET .../siteSearch?filter=categoryCode eq outerwear&facetTemplate=categoryCode:outerwear ``` A category's facet template includes the facets defined on that category, on its parent categories, and on the root template. On a keyword search results page with no category context, use `categoryCode:_root`. This loads the root template, which holds the facets configured for search results. ``` GET .../siteSearch?query=jacket&facetTemplate=categoryCode:_root ``` ### facet A comma-separated list of extra fields to facet on, in addition to the template. Use the attribute's fully qualified name for custom attributes. ``` GET .../siteSearch?query=jacket&facet=tenant~brand,tenant~color ``` Add `omitNamespace=true` to pass and receive attribute names without the `tenant~` prefix. ### facetTemplateSubset and facetTemplateExclude Both take a comma-separated list of facet field names from the template: * `facetTemplateSubset` returns only the listed facets. * `facetTemplateExclude` returns every template facet except the listed ones. If you pass both, Kibo uses `facetTemplateExclude` and ignores `facetTemplateSubset`. ``` GET .../siteSearch?query=jacket&facetTemplate=categoryCode:_root&facetTemplateSubset=tenant~brand,price ``` ### Apply a Facet Value When a shopper selects a facet value, pass that value's `filterValue` from the response in `facetValueFilter`. The format is `field:value`. Separate multiple values with commas. ``` GET .../siteSearch?query=jacket&facetTemplate=categoryCode:_root&facetValueFilter=tenant~color:blue,tenant~color:black,tenant~brand:acme ``` Values for the same field are combined with OR. Values for different fields are combined with AND. The example above returns jackets that are blue or black and are made by Acme. The applied values come back with `isApplied: true`. ### Range Facets and facetFieldRangeQuery A range facet groups numeric values, such as price, into buckets. Ranges set up in the facet template are used automatically. To build a range facet on the fly, pass `facetFieldRangeQuery` with one or more `field:[start TO end]` ranges. Use `*` for an open end. ``` GET .../siteSearch?query=jacket&facet=price&facetFieldRangeQuery=price:[* TO 50],price:[50 TO 100],price:[100 TO *] ``` If the template already defines ranges for the field, the template ranges are used instead. To filter on a range facet, pass the range in `facetValueFilter`. The range does not have to match one of the defined buckets, so you can support a price slider: ``` GET .../siteSearch?query=jacket&facetTemplate=categoryCode:_root&facetValueFilter=price:[38 TO 105] ``` ### Category Facets: facetHierValue and facetHierDepth The category facet is hierarchical. Two parameters control which part of the category tree it returns: * `facetHierValue` sets the category to start from, as `categoryCode:{code}` or `categoryId:{id}`. The facet then returns that category and its subcategories instead of the whole tree. Use `categoryCode:_root` to start from the top of the tree. * `facetHierDepth` limits how many levels of subcategories are returned, as `categoryCode:{levels}` or `categoryId:{levels}`. With `0`, only the starting category is returned. With `1`, its direct subcategories are included. Use the same field name (`categoryCode` or `categoryId`) as the category facet in your template. ``` GET .../siteSearch?filter=categoryCode eq outerwear&facetTemplate=categoryCode:outerwear&facetHierValue=categoryCode:outerwear&facetHierDepth=categoryCode:1 ``` ### Facet Value Sort and Prefix * `facetValueSort` sorts the values of a facet, as `field:sortType`. Valid sort types are `CountAscending`, `CountDescending`, `ValuesAscending`, `ValuesDescending`, `AttributeDefinition`, `AttributeDefinitionDescending`, `Count`, and `Index`. Facets from a template use the sort set in the template. The default for other facets is `CountDescending`. * `facetPrefix` returns only values that start with a prefix, as `field:prefix`. ``` GET .../siteSearch?query=jacket&facet=tenant~brand&facetValueSort=tenant~brand:ValuesAscending ``` ## Spell Correction When spell correction is turned on in your [search configuration](https://docs.kibocommerce.com/pages/spell-correction.md), keyword searches can correct misspelled queries: * **Autocorrect**: if the query returns no results and a correction exists, Kibo runs the corrected query instead. The response `spellcheck` object has `autoCorrected: true`, the `originalQuery`, and the `correctedQuery`. * **Did you mean**: the response `spellcheck.candidateCorrections` lists suggested queries you can offer to the shopper. Use `spellcorrectOverride` to turn these off for a single request: | Value | Effect | | - | - | | `Default` | Use the search configuration. This is the default. | | `SkipAutocorrect` | Do not autocorrect. Did you mean suggestions are still returned. | | `SkipDidyoumean` | Do not return Did you mean suggestions. Autocorrect still runs. | | `SkipAll` | Turn off both. | ## Merchandizing Rules [Merchandizing rules](https://docs.kibocommerce.com/pages/merchandizing-rules.md) boost, bury, pin, or block products for a search term or category. Kibo picks the matching rule for you: * For a keyword search, Kibo matches the rule by the `query` value. * For a request without a `query` value, Kibo matches the rule by category when `filter` limits results to a single category. To apply a specific rule instead of the matched one, pass its code in `merchandizingRuleCode`: ``` GET .../siteSearch?query=jacket&merchandizingRuleCode=holiday-outerwear ``` Rules apply only when the request has no `sortBy` value. The named rule also needs a search term or a single-category filter on the request. When a Merchandizing rule applies, personalization ranking is not applied to that request. ## Choose the Response Fields ### fieldList (siteSearch) `siteSearch` returns only `productCode` for each item unless you list more fields in `fieldList`. Common fields include `productName`, `priceL`, `priceH`, `productImageUrls`, `categoryCode`, `productShortDescription`, and custom attribute names. See [Site Search API](https://docs.kibocommerce.com/pages/integrating-personalization-with-search.md#site-search-api) for more examples. ### responseFields `responseFields` trims the JSON response on any Kibo API, including both search endpoints. For example, `responseFields=totalCount,items(productCode,content(productName)),facets` on `search`. See [Limit Data Returned from API Calls](https://docs.kibocommerce.com/pages/application-development-best-practices.md#limit-data-returned-from-api-calls) for the syntax. ## Worked Examples ### Keyword Search Results Page ``` GET .../siteSearch?query=hiking boots &fieldList=productName,priceL,priceH,productImageUrls &facetTemplate=categoryCode:_root &pageSize=24&startIndex=0 ``` ### Category Listing Page with a Selected Facet and Sort ``` GET .../siteSearch?filter=categoryCode eq outerwear &facetTemplate=categoryCode:outerwear &facetValueFilter=tenant~color:blue &sortBy=price asc &fieldList=productName,priceL,priceH,productImageUrls &pageSize=24 ``` ### Price Slider ``` GET .../siteSearch?query=jacket &facetTemplate=categoryCode:_root &facetValueFilter=price:[38 TO 105] &fieldList=productName,priceL,priceH ``` ### In Stock at a Store ``` GET .../siteSearch?query=shirt &filter=locationsInStock eq STORE-01 &fieldList=productName,priceL ``` ### Export Every Product in a Category ``` GET .../siteSearch?filter=categoryCode eq outerwear&fieldList=productName&pageSize=500&cursorMark=* ``` Repeat with `cursorMark` set to each `nextCursorMark` until the response has none. ## Related Topics * [Sorting and Filtering APIs](https://docs.kibocommerce.com/pages/sorting-and-filtering-apis.md) * [Facets](https://docs.kibocommerce.com/pages/facets.md) * [Spell Correction](https://docs.kibocommerce.com/pages/spell-correction.md) * [Merchandizing Rules](https://docs.kibocommerce.com/pages/merchandizing-rules.md) * [Integrating Personalization With Search](https://docs.kibocommerce.com/pages/integrating-personalization-with-search.md) * [Kibo Storefront Catalog API Developer Guide](https://docs.kibocommerce.com/developer-guides/storefront-catalog.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.