# Scoring by metric
- Operation ID: `PostItemsByMetric`
- HTTP method: `POST`
- Path: `/recommendations/v2/recommend/items/metric`
- [Human-readable API reference](https://hub.synerise.com/api-reference/ai-suite#operation/PostItemsByMetric)
## Self-contained OpenAPI method
The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.
```yaml
openapi: 3.0.0
info:
title: Synerise Public API
version: 1.9.1
paths:
/recommendations/v2/recommend/items/metric:
post:
summary: Scoring by metric
description: |
Returns items with the highest score of a chosen metric. A list of available metrics can be checked by using [this endpoint](https://developers.synerise.com/AnalyticsSuite/AnalyticsSuite.html#operation/ApiGetAvailableMetricsV2).
**Note:** The definition of an *item* encompasses products, but also articles, images, videos, and any other entities in the item feed.
---
**API consumers:** AI API key (legacy), Workspace (Business Profile), Web SDK Tracker
**API key permission required:** `RECOMMENDATIONS_V2_METRICS_RECOMMENDATIONS_READ`
operationId: PostItemsByMetric
tags:
- Recommendations
security:
- TrackerKey: []
- JWT: []
requestBody:
content:
application/json:
schema:
allOf:
- allOf:
- type: object
properties:
campaignId:
type: string
description: The campaignId which will be passed as *utm_campaign* in a link to the recommended item.
default: defaultCampaign
campaignName:
type: string
description: The campaign name which will be included in the recommendation.generated event.
catalogId:
type: string
description: ID (_not_ name) of the item feed to use in the request. The requested recommendation type (model) must be ready for this item feed.
default: default
clientUUID:
type: string
description: |
Profile UUID. This parameter is required for these recommendation types:
- Personalized
- Last seen
- Recent interactions
- Section
- Attribute
This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds:
type: array
description: Item identifiers, equal to `itemId` from the *item feed*. They can be used to define the item context of the query.
items:
type: string
description: Item identifier (`itemId` in item catalog)
includeContextItems:
type: boolean
default: false
description: The recommendation results will include context items from the request.
filterRules:
type: object
description: Filter configuration
properties:
excludePurchasedItems:
description: |
When true, the recommendation results will include only items that the Profile hasn't purchased before.
**IMPORTANT**: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
type: boolean
default: false
excludePurchasedItemsSinceDays:
description: Limits the application of the `excludePurchasedItems` filter to a specified number of days.
type: integer
elasticExcludePurchasedItems:
description: |
When true, the recommendation results will include only items that the Profile hasn't purchased before.
**IMPORTANT**: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
type: boolean
default: false
elasticExcludePurchasedItemsSinceDays:
description: Limits the application of the `excludePurchasedItems` filter to a specified number of days.
type: integer
displayAttributes:
type: string
description: Attributes to be returned
abTestContext:
type: object
description: A/B test context.
properties:
experimentId:
type: integer
description: Experiment ID which will be included in the `recommendation.generated` event.
variantId:
type: string
description: Campaign variant ID which will be included in the `recommendation.generated` event.
requestedCampaignId:
type: string
description: Requested campaign ID which will be included in the `recommendation.generated` event.
params:
type: object
example:
source: mobile
description: Extra parameters that will be added to the `recommendation.generated` event. The total size must not exceed 500 bytes.
inventoryContext:
description: |
Inventory context used to evaluate inventory-related filters and boosting strategies.
Can be either a single inventory context or
a multi-inventory context (set of channel IDs per inventory).
oneOf:
- type: object
description: |
Single inventory context.
properties:
channelIds:
type: array
items:
type: string
description: |
List of channel identifiers used to evaluate inventory-related filters and boosting strategies.
required:
- channelIds
- type: object
description: |
Multi-inventory context where each inventory can have its own set of channel IDs.
properties:
inventoryCatalogs:
type: object
additionalProperties:
type: object
description: |
Context definition for a specific inventory.
properties:
channelIds:
type: array
items:
type: string
description: |
List of channel identifiers for this specific inventory.
required:
- channelIds
description: |
Map of inventory ID to inventory context definition. Each inventory can have its own set of channel IDs.
required:
- inventoryCatalogs
- type: object
properties:
keepSlotsOrder:
type: boolean
default: true
description: |
- When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot.
- When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect.
The additional `extras.slots` object always shows slots and items as if this setting was `true`.
If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder:
type: boolean
default: false
description: |
Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns.
If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric:
type: string
description: ID of the metric to sort the results by. The list of available metrics can be checked by using [this endpoint](https://developers.synerise.com/AnalyticsSuite/AnalyticsSuite.html#operation/ApiGetAvailableMetricsV2).
boostingParameters:
type: object
description: Result boosting parameters
properties:
metric:
type: string
description: ID of the metric to boost the results by. Metric scores will be combined with recommendation scores, favoring the best-performing results. The list of available metrics can be checked by using [this endpoint](https://developers.synerise.com/AnalyticsSuite/AnalyticsSuite.html#operation/ApiGetAvailableMetricsV2).
strength:
type: number
description: How much influence the `boostMetric` has. Values less than 0 allow you to demote items that have high metric score, values greater than 0 allow you to promote items that have high metric score. A strength with a value of 0 does not change the scoring.
format: float
personalizedBoostingStrength:
type: number
description: How much influence the personalized scoring has. Greater values allow you to promote items that have high personalized score. A strength with a value of 0 does not change the scoring.
format: float
minimum: 0
maximum: 100
default: 0
boostingStrategies:
type: array
description: Boosting strategies
items:
type: object
description: Boosting strategy allows you to promote or demote specific types of products in recommendation scoring
properties:
name:
type: string
description: Boosting strategy name
condition:
type: string
description: The condition that indicates on which items the boost will be performed. The condition must comply with the rules of creating filters.
strength:
type: number
description: How much influence the strategy has. Values less than 1.0 allow you to demote items that meet the condition, values greater than 1.0 allow you to promote items that meet the condition. A strength with a value of 1.0 does not change the scoring.
format: float
minimum: 0
maximum: 2
default: 1
required:
- name
- condition
- strength
crossWorkspaceMode:
type: object
description: Specifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
properties:
enabled:
type: boolean
description: Defines if cross-workspace mode is enabled.
slots:
type: array
description: Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.
minItems: 1
items:
type: object
properties:
name:
type: string
description: Slot name
minNumItems:
type: integer
description: The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
default: 1
minimum: 1
maxNumItems:
type: integer
description: The maximal number of returned item recommendations.
maximum: 100
default: 5
shuffleNumItems:
type: integer
description: When this parameter is provided, this many best item recommendations are provided. A number of them, no more than the value of `maxItemNums`, are chosen randomly for recommendation.
minimum: 1
maximum: 200
filters:
type: string
description: |
This string defines the criteria that an item must meet in order to be considered for recommendation.
For information on building filters, see ["Items Query Language (IQL)" in the Developer Guide](https://hub.synerise.com/developers/iql/).
elasticFilters:
description: |
This string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria.
For information on building filters, see ["Items Query Language (IQL)" in the Developer Guide](https://hub.synerise.com/developers/iql/).
type: string
distinctFilter:
type: object
description: Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
properties:
elastic:
type: boolean
description: When TRUE, allows to complete the recommended items with items which don't meet the distinct filter criteria.
filters:
type: array
minItems: 1
maxItems: 5
description: Array of distinct filters
items:
type: object
properties:
field:
type: string
description: Attribute name
maxNumItems:
type: number
format: integer
description: Max number of items with the same value of the attribute
levelRangeModifier:
type: number
format: integer
description: Parameter used (for the `category` field) to specify how many categories to cut off from the end
required:
- field
- maxNumItems
required:
- elastic
- filters
required:
- slots
- type: object
required:
- sortMetric
- clientUUID
description: Definition of the requested recommendation
required: true
responses:
"200":
description: Items with the highest metric scores
content:
application/json:
schema:
allOf:
- type: object
properties:
extras:
type: object
description: Additional data
properties:
correlationId:
type: string
description: Correlation ID that allows you to link the "item clicked" events with the "recommendation generated" event that's created for each recommendation result.
contextItems:
type: array
nullable: true
description: A list of context items provided in the request
items:
type: object
properties:
itemId:
type: string
description: Item identifier (`itemId` in item catalog)
additionalProperties: true
required:
- itemId
campaignId:
type: string
description: ID of the context campaign
nullable: true
data:
type: array
description: A list of recommended items
items:
type: object
properties:
itemId:
type: string
description: Item identifier (`itemId` in item catalog)
additionalProperties: {}
required:
- itemId
- type: object
properties:
extras:
type: object
properties:
slots:
type: array
description: A list of slots data
items:
type: object
properties:
id:
type: integer
description: Slot identifier. Matches the index (zero-based numbering) of the slot provided in request
name:
type: string
description: Slot name provided in request
itemIds:
type: array
description: A list of item ids that meet the slot criteria
items:
type: string
description: Item identifier (`itemId` in item catalog)
error:
type: object
description: Details of an error, if applicable
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
status:
type: integer
description: Status code
error:
type: string
description: Summary of the error
message:
type: string
description: Description of the problem
path:
type: string
description: URL of the requested resource
required:
- timestamp
- status
- message
required:
- id
required:
- slots
"404":
description: No recommendations could be generated for the specified profile and filters
content:
application/json:
schema:
type: object
description: Details of an error, if applicable
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
status:
type: integer
description: Status code
error:
type: string
description: Summary of the error
message:
type: string
description: Description of the problem
path:
type: string
description: URL of the requested resource
required:
- timestamp
- status
- message
"500":
description: An error occurred
content:
application/json:
schema:
type: object
description: Details of an error, if applicable
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
status:
type: integer
description: Status code
error:
type: string
description: Summary of the error
message:
type: string
description: Description of the problem
path:
type: string
description: URL of the requested resource
required:
- timestamp
- status
- message
x-snr-doc-urls:
- /api-reference/ai-recommendations#tag/Recommendations/operation/PostItemsByMetric
x-codeSamples:
- lang: cURL
label: cURL
source: |-
curl --request POST \
--url https://api.synerise.com/recommendations/v2/recommend/items/metric \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}'
- lang: Python
label: Python
source: |-
import http.client
conn = http.client.HTTPSConnection("api.synerise.com")
payload = "{\"campaignId\":\"defaultCampaign\",\"campaignName\":\"string\",\"catalogId\":\"default\",\"clientUUID\":\"string\",\"contextItemIds\":[\"string\"],\"includeContextItems\":false,\"filterRules\":{\"excludePurchasedItems\":false,\"excludePurchasedItemsSinceDays\":0,\"elasticExcludePurchasedItems\":false,\"elasticExcludePurchasedItemsSinceDays\":0},\"displayAttributes\":\"string\",\"abTestContext\":{\"experimentId\":0,\"variantId\":\"string\",\"requestedCampaignId\":\"string\"},\"params\":{\"source\":\"mobile\"},\"inventoryContext\":{\"channelIds\":[\"string\"]},\"keepSlotsOrder\":true,\"personalizeSlotsOrder\":false,\"sortMetric\":\"string\",\"boostingParameters\":{\"metric\":\"string\",\"strength\":0.1,\"personalizedBoostingStrength\":0},\"boostingStrategies\":[{\"name\":\"string\",\"condition\":\"string\",\"strength\":1}],\"crossWorkspaceMode\":{\"enabled\":true},\"slots\":[{\"name\":\"string\",\"minNumItems\":1,\"maxNumItems\":5,\"shuffleNumItems\":1,\"filters\":\"string\",\"elasticFilters\":\"string\",\"distinctFilter\":{\"elastic\":true,\"filters\":[{\"field\":\"string\",\"maxNumItems\":0,\"levelRangeModifier\":0}]}}]}"
headers = {
'Authorization': "Bearer REPLACE_BEARER_TOKEN",
'content-type': "application/json"
}
conn.request("POST", "/recommendations/v2/recommend/items/metric", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
- lang: JavaScript
label: JavaScript
source: |-
const data = JSON.stringify({
"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": [
"string"
],
"includeContextItems": false,
"filterRules": {
"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {
"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"params": {
"source": "mobile"
},
"inventoryContext": {
"channelIds": [
"string"
]
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {
"metric": "string",
"strength": 0.1,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [
{
"name": "string",
"condition": "string",
"strength": 1
}
],
"crossWorkspaceMode": {
"enabled": true
},
"slots": [
{
"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {
"elastic": true,
"filters": [
{
"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.synerise.com/recommendations/v2/recommend/items/metric");
xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
- lang: Node.js
label: Node.js
source: |-
const http = require("https");
const options = {
"method": "POST",
"hostname": "api.synerise.com",
"port": null,
"path": "/recommendations/v2/recommend/items/metric",
"headers": {
"Authorization": "Bearer REPLACE_BEARER_TOKEN",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
campaignId: 'defaultCampaign',
campaignName: 'string',
catalogId: 'default',
clientUUID: 'string',
contextItemIds: ['string'],
includeContextItems: false,
filterRules: {
excludePurchasedItems: false,
excludePurchasedItemsSinceDays: 0,
elasticExcludePurchasedItems: false,
elasticExcludePurchasedItemsSinceDays: 0
},
displayAttributes: 'string',
abTestContext: {experimentId: 0, variantId: 'string', requestedCampaignId: 'string'},
params: {source: 'mobile'},
inventoryContext: {channelIds: ['string']},
keepSlotsOrder: true,
personalizeSlotsOrder: false,
sortMetric: 'string',
boostingParameters: {metric: 'string', strength: 0.1, personalizedBoostingStrength: 0},
boostingStrategies: [{name: 'string', condition: 'string', strength: 1}],
crossWorkspaceMode: {enabled: true},
slots: [
{
name: 'string',
minNumItems: 1,
maxNumItems: 5,
shuffleNumItems: 1,
filters: 'string',
elasticFilters: 'string',
distinctFilter: {
elastic: true,
filters: [{field: 'string', maxNumItems: 0, levelRangeModifier: 0}]
}
}
]
}));
req.end();
- lang: PHP
label: PHP
source: |-
setUrl('https://api.synerise.com/recommendations/v2/recommend/items/metric');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders([
'Authorization' => 'Bearer REPLACE_BEARER_TOKEN',
'content-type' => 'application/json'
]);
$request->setBody('{"campaignId":"defaultCampaign","campaignName":"string","catalogId":"default","clientUUID":"string","contextItemIds":["string"],"includeContextItems":false,"filterRules":{"excludePurchasedItems":false,"excludePurchasedItemsSinceDays":0,"elasticExcludePurchasedItems":false,"elasticExcludePurchasedItemsSinceDays":0},"displayAttributes":"string","abTestContext":{"experimentId":0,"variantId":"string","requestedCampaignId":"string"},"params":{"source":"mobile"},"inventoryContext":{"channelIds":["string"]},"keepSlotsOrder":true,"personalizeSlotsOrder":false,"sortMetric":"string","boostingParameters":{"metric":"string","strength":0.1,"personalizedBoostingStrength":0},"boostingStrategies":[{"name":"string","condition":"string","strength":1}],"crossWorkspaceMode":{"enabled":true},"slots":[{"name":"string","minNumItems":1,"maxNumItems":5,"shuffleNumItems":1,"filters":"string","elasticFilters":"string","distinctFilter":{"elastic":true,"filters":[{"field":"string","maxNumItems":0,"levelRangeModifier":0}]}}]}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
- lang: Java
label: Java
source: |-
HttpResponse response = Unirest.post("https://api.synerise.com/recommendations/v2/recommend/items/metric")
.header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
.header("content-type", "application/json")
.body("{\"campaignId\":\"defaultCampaign\",\"campaignName\":\"string\",\"catalogId\":\"default\",\"clientUUID\":\"string\",\"contextItemIds\":[\"string\"],\"includeContextItems\":false,\"filterRules\":{\"excludePurchasedItems\":false,\"excludePurchasedItemsSinceDays\":0,\"elasticExcludePurchasedItems\":false,\"elasticExcludePurchasedItemsSinceDays\":0},\"displayAttributes\":\"string\",\"abTestContext\":{\"experimentId\":0,\"variantId\":\"string\",\"requestedCampaignId\":\"string\"},\"params\":{\"source\":\"mobile\"},\"inventoryContext\":{\"channelIds\":[\"string\"]},\"keepSlotsOrder\":true,\"personalizeSlotsOrder\":false,\"sortMetric\":\"string\",\"boostingParameters\":{\"metric\":\"string\",\"strength\":0.1,\"personalizedBoostingStrength\":0},\"boostingStrategies\":[{\"name\":\"string\",\"condition\":\"string\",\"strength\":1}],\"crossWorkspaceMode\":{\"enabled\":true},\"slots\":[{\"name\":\"string\",\"minNumItems\":1,\"maxNumItems\":5,\"shuffleNumItems\":1,\"filters\":\"string\",\"elasticFilters\":\"string\",\"distinctFilter\":{\"elastic\":true,\"filters\":[{\"field\":\"string\",\"maxNumItems\":0,\"levelRangeModifier\":0}]}}]}")
.asString();
servers:
- description: Microsoft Azure EU
url: https://api.synerise.com
- description: Microsoft Azure USA
url: https://api.azu.synerise.com
- description: Google Cloud Platform
url: https://api.geb.synerise.com
tags:
- name: Recommendations
components:
securitySchemes:
TrackerKey:
type: apiKey
name: token
in: query
description: Authorization by tracker key sent as a query parameter. This is the same key as used in the website tracking code.
JWT:
type: http
scheme: bearer
description: |-
JWT Bearer token. The header looks like this: `Bearer {JWT}`
Remember to include the space between 'Bearer' and the token.
Generate a token via the **Authorization** endpoints.
```