Get recommendations

post

https://{yourinstance}.makaira.io/recommendation

Retrieve recommended products

Fetches product recommendations based on a configured recommendation setup. Requires API authentication.

Request

POST /recommendation

Headers

Header	Value
`Authorization`	`Bearer <token>`
`Content-Type`	`application/json`

Request Body

Field	Type	Required	Description
`recommendationId`	string	Yes	Identifier of the recommendation configuration from the Makaira admin UI.
`query.shop_id`	string	Yes	Shop identifier for multi-shop setups.
`query.language`	string	Yes	Language code for the index to query (e.g. `de`, `en`).
`productId`	string or array	No	Product ID(s) to base context-dependent recommendations on (e.g. "bought together"). The referenced products are excluded from the response.
`count`	integer	No	Maximum number of recommendations to return.
`query.use_stock`	boolean	No	When `true`, only returns in-stock products.
`oi.user.agent`	string	No	User agent for Machine Learning personalization.
`oi.user.ip`	string	No	User IP for Machine Learning personalization.
`oi.user.timezone`	string	No	User timezone for Machine Learning personalization.
`fields`	string	No	Comma-separated list of product fields to include in the response.
`enableHook`	boolean	No	Set to `false` to skip configured search query hooks. Defaults to `true`.
`mergeFilter`	boolean	No	When `true`, merges client-provided filters with the filters stored in the recommendation configuration.

Example Request

{
  "recommendationId": "homepage-recommendations",
  "query.shop_id": "1",
  "query.language": "de",
  "count": 6
}

Context-based recommendations

Pass productId to get related recommendations for a specific product (e.g. on a product detail page):

{
  "recommendationId": "bought-together",
  "query.shop_id": "1",
  "query.language": "de",
  "productId": "product-abc123",
  "count": 4
}

Response

Returns a JSON object with the recommended products grouped by recommendation ID.

Body Params

recommendationId

string

Use the configured Recommendation by identifier of the Makaira UI.

productId

Get recommendation relatated to one or multiple products. Note the these ids are exluded from the responses.

Enter single productId

query.shop_id

string

Only search in the specified shop.

query.language

string

Language used in this query. Use the same langunge abbreviation as in the makaira backend index-manager.

query.use_stock

boolean

Use stock information to filter search results. If true, only onstock:true products will be returned.

oi.user.agent

string

Required if you want to use Machine Learning on your Recommendations. Contains the user agent of the current user

oi.user.ip

string

Required if you want to use Machine Learning on your Recommendations. Contains the user ip of the current user

oi.user.timezone

string

Required if you want to use Machine Learning on your Recommendations. Contains the timezone of the current user

count

integer

How many recommendation should be returned.

isActive

boolean

Normally not necessary, but can override the default loaded by recommendationId. Determine if the recommendation is active or not

recommendationType

boolean

Normally not necessary, but can override the default loaded by recommendationId. The recommendation type that you want to use. Choose one of pictureSimilarity, textSimilarity, boughtTogether, behaviourHistoryCartBased, behaviourHistoryUserBased or none

isPopulateTextSimilarity

boolean

Normally not necessary, but can override the default loaded by recommendationId. Adds more products based on Recommendation Type "Text Similarity" if not enough results can be retrieved by original Recommendation Type (not applicable for Recommendation Types "Text Similarity" and "None")

filter

string

Normally not necessary, but can override the default loaded by recommendationId. Return only products that match all filter conditons.

boosting

string

Normally not necessary, but can override the default loaded by recommendationId. Prefer product that match the filter conditon. The boostingStrength value changes the importance of this attribute (logarithmic scale).

randomness

boolean

Normally not necessary, but can override the default loaded by recommendationId. Determine if we should use Randomize feature to effect the result.

isUseMachineLearning

boolean

Normally not necessary, but can override the default loaded by recommendationId. Determine if we should use Machine Learning feature to effect the result.

isUseRankingMix

boolean

Normally not necessary, but can override the default loaded by recommendationId. Determine if we should use Ranking Mix feature to effect the result.

requestId

string

Arbitrary Id to assign the request.

fields

string

List of fields that should be returned.

boostWithSimilarAttributes

boolean

Boosts Recommended items depending on simillar attributes.

mergeFilter

boolean

Decide if the filters and boostings sent from the client should be merged with the one stored in the database.

enableHook

boolean

If set to false, the search query hook will be disabled. Default value is true(if not specify)

Headers

X-Makaira-Instance

string

required

Makaira Instance ID

Response

200

Language

Credentials

Bearer

URL

Loading…

Response

Click Try It! to start a request and see the response here!