# Similar items
- Operation ID: `GetSimilarItems`
- HTTP method: `GET`
- Path: `/recommendations/v2/recommend/items/{itemId}/similar`
- [Human-readable API reference](https://hub.synerise.com/api-reference/ai-recommendations#tag/Recommendations/operation/GetSimilarItems)
## 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/{itemId}/similar:
get:
summary: Similar items
description: |
Returns items similar to a given item.
**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_SIMILAR_RECOMMENDATIONS_READ`
operationId: GetSimilarItems
tags:
- Recommendations
security:
- TrackerKey: []
- JWT: []
parameters:
- name: minNumItems
in: query
required: false
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.
schema:
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
- name: maxNumItems
in: query
required: false
description: The maximal number of returned item recommendations.
schema:
type: integer
description: The maximal number of returned item recommendations.
maximum: 100
default: 5
- name: campaignId
in: query
required: false
description: The campaignId which will be passed as *utm_campaign* in a link to the recommended item.
schema:
type: string
default: defaultCampaign
- name: campaignName
in: query
required: false
description: The campaign name which will be included in the recommendation.generated event.
schema:
type: string
- name: clientUUID
in: query
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.
required: false
schema:
type: string
- in: path
name: itemId
required: true
description: Item identifier, equal to `itemId` from the *item feed*.
schema:
type: string
- name: excludePurchasedItems
in: query
required: false
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.
schema:
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
- name: excludePurchasedItemsSinceDays
in: query
required: false
description: Limits the application of the `excludePurchasedItems` filter to a specified number of days.
schema:
description: Limits the application of the `excludePurchasedItems` filter to a specified number of days.
type: integer
- name: filters
in: query
required: false
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/).
schema:
type: string
- name: elastic:filters
in: query
required: false
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/).
schema:
type: string
- name: itemCatalogId
in: query
required: false
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.
schema:
type: string
default: default
- in: query
name: distinctFilter
required: false
schema:
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
- name: includeContextItems
in: query
required: false
description: The recommendation results will include context items from the request.
schema:
type: boolean
- name: params
in: query
required: false
description: |
List of extra params that will be added to the `recommendation.generated` event. They must be in the `name:value` format. The total size must not exceed 500 bytes when written as a JSON object.
example:
- source:mobile
schema:
type: array
items:
type: string
- name: inventoryChannelId
in: query
required: false
description: |
Inventory context identifier used to evaluate inventory-related filters and boosting strategies. If not provided, no inventory context will be applied.
schema:
type: string
- name: crossWorkspaceMode
in: query
required: false
description: |
Specifies if recommendation should use cross-workspace mode and personalize recommendations with events from other members of workspace group if they are available.
schema:
type: boolean
responses:
"200":
description: Items similar to the given item
content:
application/json:
schema:
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
"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/GetSimilarItems
x-codeSamples:
- lang: cURL
label: cURL
source: |-
curl --request GET \
--url 'https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE¶ms=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE' \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
- lang: Python
label: Python
source: |-
import http.client
conn = http.client.HTTPSConnection("api.synerise.com")
headers = { 'Authorization': "Bearer REPLACE_BEARER_TOKEN" }
conn.request("GET", "/recommendations/v2/recommend/items/%7BitemId%7D/similar?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE¶ms=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
- lang: JavaScript
label: JavaScript
source: |-
const data = null;
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE¶ms=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE");
xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");
xhr.send(data);
- lang: Node.js
label: Node.js
source: |-
const http = require("https");
const options = {
"method": "GET",
"hostname": "api.synerise.com",
"port": null,
"path": "/recommendations/v2/recommend/items/%7BitemId%7D/similar?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE¶ms=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE",
"headers": {
"Authorization": "Bearer REPLACE_BEARER_TOKEN"
}
};
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.end();
- lang: PHP
label: PHP
source: |-
setUrl('https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar');
$request->setMethod(HTTP_METH_GET);
$request->setQueryData([
'minNumItems' => 'SOME_INTEGER_VALUE',
'maxNumItems' => 'SOME_INTEGER_VALUE',
'campaignId' => 'SOME_STRING_VALUE',
'campaignName' => 'SOME_STRING_VALUE',
'clientUUID' => 'SOME_STRING_VALUE',
'excludePurchasedItems' => 'SOME_BOOLEAN_VALUE',
'excludePurchasedItemsSinceDays' => 'SOME_INTEGER_VALUE',
'filters' => 'SOME_STRING_VALUE',
'elastic:filters' => 'SOME_STRING_VALUE',
'itemCatalogId' => 'SOME_STRING_VALUE',
'distinctFilter' => 'SOME_OBJECT_VALUE',
'includeContextItems' => 'SOME_BOOLEAN_VALUE',
'params' => 'source:mobile',
'inventoryChannelId' => 'SOME_STRING_VALUE',
'crossWorkspaceMode' => 'SOME_BOOLEAN_VALUE'
]);
$request->setHeaders([
'Authorization' => 'Bearer REPLACE_BEARER_TOKEN'
]);
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
- lang: Java
label: Java
source: |-
HttpResponse response = Unirest.get("https://api.synerise.com/recommendations/v2/recommend/items/%7BitemId%7D/similar?minNumItems=SOME_INTEGER_VALUE&maxNumItems=SOME_INTEGER_VALUE&campaignId=SOME_STRING_VALUE&campaignName=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&excludePurchasedItems=SOME_BOOLEAN_VALUE&excludePurchasedItemsSinceDays=SOME_INTEGER_VALUE&filters=SOME_STRING_VALUE&elastic%3Afilters=SOME_STRING_VALUE&itemCatalogId=SOME_STRING_VALUE&distinctFilter=SOME_OBJECT_VALUE&includeContextItems=SOME_BOOLEAN_VALUE¶ms=source%3Amobile&inventoryChannelId=SOME_STRING_VALUE&crossWorkspaceMode=SOME_BOOLEAN_VALUE")
.header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
.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.
```