Get public recommendations

post

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

Public Endpoint to retrieve recommended products

Fetches product recommendations without requiring API-secret authentication. Suitable for direct storefront use. Response fields are limited to those configured in the recommendation setup.

Request

POST /recommendation/public

Headers

Header	Value
`Content-Type`	`application/json`
`X-Makaira-Instance`	Your Makaira instance identifier

Request Body

Field	Type	Required	Description
`recommendationId`	string or array	Yes	Identifier(s) of the recommendation configuration(s). Pass an array to fetch multiple recommendation sets in one request.
`query.shop_id`	string	Yes	Shop identifier.
`query.language`	string	Yes	Language code for the index (e.g. `de`, `en`).
`productId`	string	No	Product ID to base context-dependent recommendations on.
`count`	integer	No	Maximum number of recommendations per recommendation set.
`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.
`enableHook`	boolean	No	Set to `false` to skip search query hooks. Defaults to `true`.

Example Request

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

Fetch Multiple Recommendation Sets

{
  "recommendationId": [
    "homepage-recommendations",
    "trending-products"
  ],
  "query.shop_id": "1",
  "query.language": "de",
  "count": 4
}

Response

Returns a JSON object keyed by recommendation ID, each containing an array of recommended product items.

Body Params

recommendationId

Use the configured Recommendation by identifier of the Makaira UI.

Enter single recommendationId

productId

string

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

query.shop_id

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

string

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

integer

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

string

enum

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

Allowed:

isPopulateTextSimilarity

string

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

boolean

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

string

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

array

List of fields that should be returned.

fields

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.

constraints

object

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!