searchProduct
Search products by title.
Description
Searches products by the text in name, matching the title in localizeInfos for the language set by langCode. Resolves to an array of IProductsEntity objects, or [] when nothing matches. With traficLimit: true in the defineOneEntry config, it resolves to short IProductSearchResult cards instead.
What you get depends on traficLimit
The declared return type is IProductsEntity[] | IProductSearchResult[] | IError:
| Config | Result | Contains |
|---|---|---|
traficLimit: false (default) | IProductsEntity[] | Full product entities, with attributeValues, localizeInfos, blocks, … |
traficLimit: true | IProductSearchResult[] | The raw quick-search card: only { id, title, pageId } |
Short cards have no attributeValues, and the call can also resolve to an IError, so narrow the result before reading it:
const found = await Products.searchProduct('cos');
if (!Array.isArray(found)) {
// IError: the request failed
} else if (found.length === 0) {
// nothing matched
} else if ('attributeValues' in found[0]) {
// IProductsEntity[]: traficLimit is off
} else {
// IProductSearchResult[]: short { id, title, pageId } cards
}
.searchProduct(
,
,
,
);
Parameters schema
Schema
name(required): string
Text to search for in product titles (localizeInfos.title) in the requested language.
example: "laminat"
langCode: string
Language code. Default: the langCode passed to defineOneEntry ("en_US" if none).
example: "en_US"
url: string
URL of a catalog page to search within that category. Default: the whole catalog.
example: the whole catalog
correct: boolean
Correct typos by the project's search dictionary first. The API defaults to true; pass false to search the query as is.
Examples
Minimal example
const response = await Products.searchProduct('cos');
Example with langCode
const response = await Products.searchProduct('cos', 'en_US');
Example response
[
{
"id": 2957,
"localizeInfos": {
"title": "Cosmo"
},
"isVisible": true,
"isSync": false,
"sku": null,
"price": 150,
"additional": {
"prices": {
"min": 51,
"max": 180
}
},
"categories": [
"catalog"
],
"statusIdentifier": "sale",
"statusLocalizeInfos": {
"title": "Sale"
},
"templateIdentifier": null,
"shortDescTemplateIdentifier": null,
"attributeValues": {
"product-name": {
"type": "string",
"value": "Cosmo",
"isIcon": false,
"position": 0,
"additionalFields": {},
"isProductPreview": false
},
"price": {
"type": "integer",
"value": 150,
"isIcon": false,
"position": 1,
"additionalFields": {},
"isProductPreview": false
},
"currency_products": {
"type": "string",
"value": "USD",
"isIcon": false,
"position": 2,
"additionalFields": {},
"isProductPreview": false
},
"img": {
"type": "image",
"value": "",
"isIcon": false,
"position": 3,
"additionalFields": {},
"isProductPreview": true
}
},
"attributeSetIdentifier": "products",
"isPositionLocked": false,
"position": 1,
"rating": {},
"paymentStages": null,
"productPages": [
{
"id": 2850,
"pageId": 10,
"productId": 2957,
"positionId": 3193,
"categoryPath": "catalog"
}
],
"blocks": [
"product_block",
"similar"
],
"moduleFormConfigs": [
{
"id": 12,
"formIdentifier": "review",
"moduleIdentifier": "catalog",
"isGlobal": false,
"isClosed": false,
"isModerate": false,
"viewOnlyMyData": false,
"commentOnlyMyData": false,
"entityIdentifiers": [
{
"id": "catalog",
"isNested": true
}
],
"formDataCount": 823,
"ratingCalculation": "average",
"allowHalfRatings": null,
"maxRatingScale": null,
"isAnonymous": null,
"allowRerating": null,
"isRating": null,
"entityFormDataCount": {
"2954": 823
},
"nestedEntityIdentifiers": [
"catalog"
],
"exceptionIds": []
}
],
"discountConfig": {}
}
]
Response schema
Schema: IProductsEntity[] | IProductSearchResult[]
id: number
ID of the product.
example: 12345
localizeInfos: ILocalizeInfo
Localized product data, such as the title.
example:
{}
statusIdentifier: string | null
Marker of the product status, or null.
example: "in_stock"
statusLocalizeInfos: ILocalizeInfo
Localized status name for the product.
example:
{ "title": "Sale" }
attributeSetIdentifier: string | null
Marker of the attribute set, or null if none is assigned.
example: "set_12345"
position: number
Position used for sorting. Present on catalog/list/ids//blocks entities; absent from vector (semantic) search results, so typed optional.
example: 1
price: number | null
Product price from the search index.
example: 150.00
additional: object
Extra values computed by the search index, such as the price range in prices.min and prices.max.
example:
{
"prices": {
"min": 5,
"max": 150
}
}
sku: string | null
Product SKU from the search index, or null.
example: "SKU_12345"
isSync: boolean
Whether the product's attribute index is up to date for the requested language. When false, an empty or partial attributeValues means the values are not published yet, not that there are none.
example: true
attributeValues: IAttributeValues
Attribute values keyed by attribute marker (an object, not an array).
example:
{
"product-name": {
"type": "string",
"value": "Split",
"position": 0
},
"price": {
"type": "integer",
"value": 150,
"position": 1
}
}
categories: string[]
URLs of the catalog pages the product belongs to.
example:
[
"catalog"
]
isVisible: boolean
Whether the product is visible.
example: true
moduleFormConfigs: Array<IFormConfig>
Form configurations of the module.
rating: IRating
Rating data: average value, likes and dislikes, and the calculation method.
isPositionLocked: boolean
Whether the sorting position is locked.
example: false
relatedIds: number[]
IDs of related products.
example:
[
12345,
67890
]
paymentStages: unknown
Payment stages of the product: an array of { title, value, marker } objects, or null when none are set.
example: null
distance: number
Relevance distance in vector (semantic) search. Present only in vector search results.
example: 0.42
discountConfig: Record<string, unknown>
Discount configuration.
example:
{}
templateIdentifier: string | null
Marker of the linked template.
example: "template_12345"
shortDescTemplateIdentifier: string | null
Marker of the template used for the short description.
example: "short_desc_template_12345"
signedPrice: string
Signed token (JWT) that fixes the product price for an order. Returned when signPrice is set.
see: Fixed product price
example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
productPages: IProductPageRef[]
Links between the product and the catalog pages it belongs to.
example:
[
{
"id": 16,
"pageId": 4,
"productId": 15,
"positionId": 244,
"categoryPath": "products"
}
]
productPages.id: number
ID of the product-to-page link record.
example: 16
productPages.pageId: number
Identifier of the page the product is linked to.
example: 4
productPages.productId: number
Product ID.
example: 15
productPages.positionId: number
ID of the position record that stores the product's sort order.
example: 244
productPages.categoryPath: string
Category path of the page the product belongs to.
example: "products"
blocks: string[]
Markers of the blocks shown on the product page (not the blocks whose selection includes the product).
example:
[
"block_12345",
"block_67890"
]
This method can't request price fixing, so its response has no
signedPrice. To get one, call getProductsByIds() or a listing method withsignPriceset. See Fixing the price (signPrice).
Usage examples
Step-by-step walkthrough in the documentation:
- Search product: quickly look up products by title.
Try it live
Run this method in the JS SDK sandbox. On your first visit, connect your Project URL and App Token, then open:
- Search product: quickly look up products by title.