--- title: "Typeahead v1" method: POST path: "/v1/typeahead" tags: ["search-v1"] --- # Typeahead v1 `POST /v1/typeahead` The endpoint searches and returns: - brands by their name - categories by their name or their synonyms - products by their name, brand, and attributes (or attribute synonyms) When there is an exact one-to-one match present in the results, it is placed under the `topMatch` property. The rest of the results are sorted by relevancy and placed under the `suggestions` property. Sorting gives more weight to categories and brands, so products are generally placed below categories and brands. The suggestions array has two types of objects: - `BrandOrCategory` object, which is either a brand or category. Whether it is a brand or category can be identified by the property `primaryMatch`. The brand suggestions will also include the most relevant category under the `category` property. - product object When the search term finds a matching attribute, the attribute is then applied as a filter to the brand and category searches, adjusting the product count. Applied filters can be found under the `attributeFilters` property. **Please use the `?fullAttributeValue=true` parameter for all searches**. The old response that returns only attribute IDs is deprecated. The response will default to full attribute values in the future. ## Query parameters - `term` string, required - `fullAttributeValue` boolean - `limit` integer - `with` string[] - `categoryDepth` integer - `categoryId` integer ## Request body - TypeaheadRequestBody - `fuzziness` union — The fuzziness parameter can enable some typo tolerance. Available values are 0, 1, 2, and auto. Defaults to auto. Note: The value set in the SCAYLE Panel will not impact this search. - string - integer - `categoryId` integer — The `categoryId` parameter can filter by category ID. - `limit` integer — The `limit` parameter allows limiting the number of suggested products returned. - `term` string — The `term` parameter allows you to query for any entity with a full or partial match with the given term. ## Response `200` successful operation - TypeaheadResponse - `suggestions` union, required - TypeaheadBrandOrCategorySuggestion - `brandOrCategorySuggestion` BrandOrCategorySuggestion - `attributeFilters` object[], required - `id` integer - `name` string - `slug` string — short text to describe the current category (usable, for example, in URLs as `fashion`). - `values` integer[] - `brand` object, nullable, required - `id` integer - `name` string - `category` Category, required - `id` integer, required — The unique identifier of the category. - `path` string, required — The slugs for all `rootlineIds` combined with `/` (e.g., `/women/fashion`). - `name` string, required — The name of the category - `slug` string, required — A short string to describe the current category (usable, for example, in URLs as). - `parentId` integer, required — The parent category ID (root-level categories have a parent ID of `0`) - `rootlineIds` integer[], required — The IDs for the path from the topmost root category to the current category, which is included as the last item. - `childrenIds` integer[], required — The child category IDs attached to the current category - `properties` CategoryProperty[], required — Properties attached to this category. - `name` string, required - `value` union, required - … - `isHidden` boolean, required — A flag that defines if a category should be displayed by the frontend - `depth` integer, required — The nesting level of the category (root-level depth = 1, child nodes = 2, child nodes' children = 3, etc.) - `supportedFilter` string[], required — A list of filters that can be used for filtering products in the category - `parent` Category — recursive - `shopLevelCustomData` object, required — Additional category data defined on the shop level - `countryLevelCustomData` object — Additional category data defined on the country level - `children` Category[] — An array of child category objects. Returned if requested as `tree format` or using `with`. - `primaryMatch` 'brand' | 'category', required - `productCount` integer, required - `suggestion` string, required - `score` number - `type` string - TypeaheadProductSuggestion - `productSuggestion` ProductSuggestion - `suggestion` string - `product` Product - `id` integer, required - `advancedAttributes` object - `attributes` object - `baseCategories` BaseCategory[] - `categoryId` integer, required — Unique identifier of the category - `categoryName` string, required — Name of the category - `categoryParentId` integer, required — Parent ID of the category - `categoryPath` string, required — Category path as text - `categories` array[] - ProductCategory[] - … - `definingAttributes` DefiningAttribute - `id` integer, required - `label` string, required - `images` Image[], required - `attributes` object - `hash` string - `customData` ResponseCustomData, required - `isActive` boolean, required — Identifies whether a product is active or not - `isNew` boolean, required — Identifies whether a product is new or not - `isSoldOut` boolean, required — Identifies if a product is still available to sell - `masterKey` string, required — Identifies the master product which this product belongs - `firstLiveAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `priceRange` PriceRange - `max` Price, required - … - `min` Price, required - … - `reductionRange` ReductionRange - `max` Price - … - `min` Price - … - `lowestPriorPrice` LowestPriorPrice — Information about the lowest price in the past 30 days. - `withTax` integer, nullable, required — The lowest price including tax. - `relativeDifferenceToPrice` number, float, nullable, required — The relative difference from the lowest prior price to the current price. If the value is positive, it means that the current price is higher than the lowest prior price. If the value is negative, it means that the current price is lower than the lowest prior price. - `referenceKey` string, required - `searchCategoryIds` integer[] - `siblings` Product[] — list of Products - `variants` Variant[] - `id` integer, required - `advancedAttributes` object - `appliedPricePromotionKey` string - `attributes` object - `lowestPriorPrice` LowestPriorPrice — Information about the lowest price in the past 30 days. - … - `price` Price, required - … - `productId` integer, required - `referenceKey` string, required - `firstLiveAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `stock` Stock, required - … - `customData` object, required - `merchant` Merchant - … - `createdAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `updatedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `createdAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `updatedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `indexedAt` string, required — Date string, formatted according to RFC 3339, e.g. 2018-06-01T14:56:08+02:00 - `score` number - `type` string - `topMatch` object, nullable, required - `brandOrCategorySuggestion` BrandOrCategorySuggestion - `attributeFilters` object[], required - `id` integer - `name` string - `slug` string — short text to describe the current category (usable, for example, in URLs as `fashion`). - `values` integer[] - `brand` object, nullable, required - `id` integer - `name` string - `category` Category, required - `id` integer, required — The unique identifier of the category. - `path` string, required — The slugs for all `rootlineIds` combined with `/` (e.g., `/women/fashion`). - `name` string, required — The name of the category - `slug` string, required — A short string to describe the current category (usable, for example, in URLs as). - `parentId` integer, required — The parent category ID (root-level categories have a parent ID of `0`) - `rootlineIds` integer[], required — The IDs for the path from the topmost root category to the current category, which is included as the last item. - `childrenIds` integer[], required — The child category IDs attached to the current category - `properties` CategoryProperty[], required — Properties attached to this category. - `name` string, required - `value` union, required - string - number - `isHidden` boolean, required — A flag that defines if a category should be displayed by the frontend - `depth` integer, required — The nesting level of the category (root-level depth = 1, child nodes = 2, child nodes' children = 3, etc.) - `supportedFilter` string[], required — A list of filters that can be used for filtering products in the category - `parent` Category — recursive - `shopLevelCustomData` object, required — Additional category data defined on the shop level - `countryLevelCustomData` object — Additional category data defined on the country level - `children` Category[] — An array of child category objects. Returned if requested as `tree format` or using `with`. - `primaryMatch` 'brand' | 'category', required - `productCount` integer, required - `suggestion` string, required - `score` number - `type` string ## Other responses - `400` — required query parameter missing / query parameter invalid - `401` — authentication failed --- [API](https://skmtc.dev/scayle/apis/storefront-api-documentation.md) · [All operations](https://skmtc.dev/scayle/apis/storefront-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scayle/storefront-api-documentation/revisions/8cfa924ae703/schema)