--- title: "Category API" method: GET path: "/api/search/category.json" tags: [""] --- # Category API `GET /api/search/category.json` Returns category page results, filters, sort options, pagination, active filters (if active), configured merchandising data (if triggered), and spell correction information to build a category results page. See [Category Result Pages](https://docs.searchspring.com/reference/category-result-pages) to see where this endpoint is used. This endpoint should be used specifically for category page requests instead of the Search API endpoint. ## Query parameters - `siteId` string, required - `resultsFormat` string, required - `rq` string - `filter` object — Filters the array of results. Filter parameter is used when a customer applies a filter in the UI. Parameter names should be "filter.[field]", ***value*** is case sensitive. Examples: * filter.color=blue * filter.size=Large If a filter is configured to have a type of slider or if a range is specified in the advanced section, in order to use the range functionality a low and/or high value will need to be chained after the field. Examples: * filter.price.low=2 * filter.price.high=120 - `bgfilter` object — ***Required for category pages*** - Functions the same as the ***filter*** parameter except it is used to define the category scope by filtering initial results. This parameter is typically used to filter by collection_handle, category_hierarchy, or similar category-defining fields. This parameter should not be usable in the UI by a customer, see the filter parameter for customer interactions to filter results. Parameter names should be "bgfilter.[field]", ***value*** is case sensitive. Examples: * bgfilter.collection_handle=mens-shoes * bgfilter.category_hierarchy=Mens/Shoes * bgfilter.is_published=1 If a filter is configured to have a type of slider or if a range is specified in the advanced section, in order to use the range functionality a low and/or high value will need to be chained after the field. Examples: * bgfilter.price.low=2 * bgfilter.price.high=120 - `sort` object — Used to sort returned results. Parameter names should be "sort.[field]=[asc/desc]" Examples: * sort.price=asc * sort.is_bestseller=desc - `userId` string, required - `sessionId` string, required - `pageLoadId` string, required - `domain` string, required - `resultsPerPage` integer - `page` integer - `redirectResponse` 'direct' | 'minimal' | 'full' - `landing-page` string - `tag` string - `includedFacets` string - `excludedFacets` string - `disableInlineBanners` string — Will disable inline banners from being returned in the API response. - `lastViewed` string - `cart` string - `shopper` string - `beacon` boolean - `test` boolean ## Headers - `HTTP_X_FORWARDED_FOR` string ## Response `200` OK - SearchResponseModel - `pagination` object — Allows a user to define and navigate pages of the results that are returned in the API response. This is returned as an object. - `totalResults` unknown - `begin` unknown - `end` unknown - `currentPage` unknown - `totalPages` unknown - `previousPage` unknown - `nextPage` unknown - `perPage` unknown - `defaultPerPage` unknown - `sorting` object — Sorting allows a shopper to modify how the results returned by the API response are ordered. This is returned in the API response within the **options** array. The **options** array houses an array of objects, and each object represents a different sorting option that is configured in the Seachspring Management Console. Sorting options can be configured by finding the desired field to be used as a sort option on the [Field Settings](https://manage.searchspring.net/management/field-settings/display-fields) page, selecting the ***sort*** checkbox, then navigating to the [Sorting](https://manage.searchspring.net/management/express/sorting) page to activate and further configure how the sort option should behave and appear on the frontend. - `options` unknown[] — Array of objects, each object represents a sort option that is configured on the [Sorting page](https://manage.searchspring.net/management/express/sorting). - unknown - `resultLayout` string — This field is deprecated as it was previously utilized for Searchspring Integrations. - `results` SearchReponseModelResult[] — Array of objects that represent the relevant results returned after the database is queried. The way to modify the result data that is returned is through the passed query, and/or filter, and/or background filter parameter value(s). - `core` object — List of general core fields that houses data to describe a result/product. These fields are always returned in the API response and are returned by default. The values of these fields are configured on the [Core Mappings](https://manage.searchspring.net/management/field-settings/core-mapping) page in the Searchspring Management Console. ***Disclaimer - core fields will take precedence over fields with the same naming convention received in the data feed.*** For example, if a field named **price** is received in the data feed, the field and it's data that is mapped to the **price** core field in the Searchspring Management Console will take precedence. - `uid` string — Unique identifier of a result. - `sku` string — SKU of a result. - `intellisuggestData` string — Unique data identifier of a result specific for IntelliSuggest search result click tracking. - `intellisuggestSignature` string — Unique signature identifier of a result specific for IntelliSuggest search result click tracking. - `name` string — Name of a result. - `url` string — URL to the Product Display Page (PDP) of a result. - `addToCartUrl` string — URL to add the result to the cart. - `price` string — Active price of a result. - `msrp` string — Manufacturer Suggested Retail Price (MSRP) of a result. - `imageUrl` string — A normal image URL for a result. Typically will be a larger image size. - `thumbnailImageUrl` string — A smaller image URL for a result. This image will typically be rendered on smaller screen sizes. - `rating` string — Review rating of a result. - `ratingCount` string — Number of reviews a result has. - `description` string — Description of a result. - `stockMessage` string — Message that describes the current stock status of a result. - `brand` string — Brand of the result. - `popularity` string — Popularity rating of a result. - `attributes` string — Will be an object of applicable attribute fields that represent any field that is configured as ***display*** on the [Field Settings](https://manage.searchspring.net/management/field-settings/display-fields) page in the SMC. The data returned in these fields can be utilized to allow your development team to further describe or add more functionality to a result. - `facets` SearchResponseModelFilter[] — Array of objects that represent the relevant filters returned after the database is queried. If all results returned in the API response share the same data for the field, then the filter will not be returned within the facets object. - `field` string — The field that is configured on the [Field Settings page](https://manage.searchspring.net/management/field-settings/display-fields) to be used as a filter. - `label` string — Label of the filter that is displayed on the frontend. This value can be configured on either the [Field Settings page](https://manage.searchspring.net/management/field-settings/display-fields) or the [Filtering page](https://manage.searchspring.net/management/filtering) under the ***Label*** column. The default value is the name of the field's key. - `type` string — The ***type*** value returned for a filter represents the value configured in dropdown under the **Display** column seen on the [Filtering page](https://manage.searchspring.net/management/filtering). * list (default) * grid * palette * hierarchy * slider - `multiple` string — The value configured in the dropdown under the **Selection** column on the [Filtering page](https://manage.searchspring.net/management/filtering). Below is a map of the values seen on the [Filtering page](https://manage.searchspring.net/management/filtering) and how they are returned in the API response. * Default: Select Multiple - OR => NULL or "" * Select One => single * Select Multiple - AND => multiple-intersect * Select Multiple - OR => multiple-union - `collapse` integer — The value returned within the ***collapse*** property represents if a facet should be collapsed or not when the page loads. * Expanded => 0 * Collapsed => 1 - `facet_active` integer — Will determine if the facet is currently being used to filter results. The values returned are boolean values in the form of 0 and 1. * Expanded => 0 (default) * Collapsed => 1 - `values` SearchReponseModelFilterValue[] — An array of objects that represent each available filter value for a facet. The amount of values returned can be modified under the ***Max*** column on the [Filtering page](https://manage.searchspring.net/management/filtering). - `active` boolean — If there are not any filter parameters applied to the API request, then all filters should by default be false. If a filter parameter is applied to the API request, then the filter that is in use will have an ***active*** value of ***true***. - `type` string — Will always by default be ***value*** unless the filter is configured to have values be a Filter Range. If a filter is configured to have it's values returned as a filter range then the type will be ***range***. To use filter ranges see this documentation for [Filtering](https://searchspring.zendesk.com/hc/en-us/articles/201184909) under the Ranges section for more information. - `value` string — Will be the value returned by the API. This is used to pass as the value when a shopper applies a background filter, filter, or sort parameter to the API request. The ***value*** key will not be returned if a filter has a ***type*** key with a value of ***range***, ***low*** and ***high*** will be returned in it's place. - `low` string — If a filter has it's type returned as ***range***, this value will be used in place of the value returned in the ***value*** key. Low is only usable for background filter and filter parameters applied to the API request. The low value passed will dictate the beginning of the range in the returned result set. - `high` string — If a filter has it's type returned as ***range***, this value will be used in place of the value returned in the ***value*** key. High is only usable for background filter and filter parameters applied to the API request. The high value passed will dictate the end of the range in the returned result set. - `label` string — Label returned for a filter value is what will be displayed on the frontend of the site. The label can only be changed if the values are configured to be returned as a Filter Range. - `count` integer — Count will determine the amount of results that have the same value for the filter field. - `hierarchyDelimiter` string — Will be returned for a facet if the facets Display on the [Filtering page](https://manage.searchspring.net/management/filtering) is configured as a Hierarchy. The way to change the value is by navigating to and clicking on the Advanced section and setting the Hierarcy Delimiter in the dropdown. The value passed as the delimiter(separator) will tell the API to separate the filter values by that value. * **/** (default) * **>** * **~** * **:** * **,** * **#** - `step` integer — Will be returned for a facet if the facets Display on the [Filtering page](https://manage.searchspring.net/management/filtering) is configured as a slider. The value here will determine how much the slider will increment when the shopper slides the slider one space. This value is dynamically calculated based on the range of data for the configured field returned in the API response. - `active` unknown[] — Will be returned for a facet if the facets Display on the [Filtering page](https://manage.searchspring.net/management/filtering) is configured as a slider. The two values returned here will determine the available lowest and highest possible values for the field based on the relevant product data returned by the API. - unknown - `range` unknown[] — Will be returned for a facet if the facets Display on the [Filtering page](https://manage.searchspring.net/management/filtering) is configured as a slider. The two values returned here will determine the available lowest and highest possible values for the field based on the relevant product data returned by the API. - unknown - `format` string — Will be returned for a facet if the facets Display on the [Filtering page](https://manage.searchspring.net/management/filtering) is configured as a slider. The way to change the format is by navigating to and clicking on ***Advanced*** and either changing the default Custom format($%01.2f - $%01.2f) or selecting a commonly used format in the available dropdown. * $25.35 - $48.50 * 12 - 25 * 13.50 - 18.75 * 8.5 - 12.5 * $%01.2f - $%01.2f (default) - `breadcrumbs` unknown[] — Array of objects representing breadcrumbs for the current search result. If a query parameter is passed a value will be populated to indicate that a search has been made. However, if a single filter parameter is applied it will not be reflected until a secondary filter is applied. - unknown - `filterSummary` unknown[] — Each object returned within the filterSummary array will represent a filter that is currently in use to filter the result set by. Currently if a filter's Display is set as Hierarchy and if it is applied, it's usage will not be reflected in filterSummary. If a Hierarchy filter is active it will be reflected in the breadcrumbs array. - unknown - `merchandising` object — Will return an array of objects that represent the data configured in merchandising campaigns and will also return a redirect if configured. - `redirect` string — If a redirect is configured on the redirect page in the Searchspring Management Console and the ***q*** parameter value matches the configuration, then the configured redirect URL will be returned here. - `is_elevated` unknown[] — If products are elevated by IntelliSuggest an array of Searchspring ID's will be returned here. These ID's will match the first products returned in the ***results*** array. - unknown - `elevated` unknown[] — If products are pinned in a triggered merchandising campaign, an array of Searchspring ID's will be returned here. These ID's will match the first products returned in the ***results*** array. - unknown - `removed` unknown[] — If products are removed from a triggered merchandising campaign, an array of Searchspring ID's will be returned here. These ID's will match the products that will not be returned in the ***results*** array. - unknown - `content` object — If merchandising banners are configured in a triggered merchandising campaign, they will be returned here as a script that can be added to the page to render the configured banner on the site. - `header` unknown[] — Primary banner to be used on the page typically this is used above the page content below the navigation bar. - unknown - `banner` unknown[] — Secondary or sub header banner to be used on the page below the primary banner and above the page content. - unknown - `footer` unknown[] — Banner to be used at the end of the page content. - unknown - `left` unknown[] — Banner that used below the filters if the filters are left aligned, but is not limited to that orientation. - unknown - `inline` unknown[] — Will be returned as an array of objects. There are currently only a maximum of four inline banners that can be configured for a campaign. Each object will contain the banner content within the ***value*** key, and the configured position of the inline banner within the results is returned within ***config.position.index***. - unknown - `facets` unknown[] — Will represent the facets/filters that are configured to have a specific order in the merchandising campaign. - unknown - `facetsHide` unknown[] — If facets/filters are configured to be hidden in a triggered merchandising campaign they will be returned here. - unknown - `experiments` unknown[] — If the triggered merchandising campaign is apart of an active A/B experiment, then data will be returned in this array. - unknown - `triggeredCampaigns` unknown[] — An array of objects will be returned for the triggeredCampaigns array if values passed in a Search API request matches the context of a configured merchandising campaign. Typically an account will have a Global merchandising campaign setup, if one is then the Global merchandising campaign will always be returned within triggeredCampaigns along with any other campaigns that have a match. - unknown - `didYouMean` object — An object representing a spelling suggestion for the current search result. Only included for results with no results. - `query` string — The suggested query after spelling correction. - `highlighted` string — The suggested query with the spelling changes highlighted by being wrapped in elements. - `query` object — Will be returned if [Expanded Search](https://searchspring.zendesk.com/hc/en-us/articles/360050242531-Expanded-Search) or Integrated Spell Correction are enabled. Speak with your Customer Success Manager for more information about these features. - `matchType` string — Indicates the type of search matching that was required for this search. Will return ***expanded*** when an Expanded Search is applied after finding zero results for the initial strict search. - `original` string — If integrated spell correction occurs, will return the original incorrect query that was passed as the ***q*** request parameter. - `corrected` string — If integrated spell correction occurs, will return the corrected query. Returned results will reflect the ***corrected*** value. - `responseId` string — A uniquely generated ID used to identify the response. This ID is used by beacon tracking to associate user interactions with specific finder results. ## Other responses - `302` — ***Note: Redirects are not recommended for category pages.*** This status code will be returned when a category or query value passed in the API request matches a configured redirect in the Searchspring Management Console and the query parameter ***redirectResponse=direct*** is in use. - `400` — Bad Request - `403` — 403 Request generated a response that was too large - `404` — 404 Not Found - `405` — 405 Method Not Allowed - `429` — 429 Too Many Requests - `500` — Internal Server Error - `502` — Bad Gateway - `503` — This status code will be returned when the request hits a timeout of 5 seconds. --- [API](https://skmtc.dev/searchspring/apis/autocomplete-module.md) · [All operations](https://skmtc.dev/searchspring/apis/autocomplete-module/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/searchspring/autocomplete-module/revisions/04129662b4e5/schema)