Similar Products
const url = 'https://api.vviinn.com/similar-products';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"requestId":"6edf9d4d-60e8-49f3-b120-e89d728b8a89","productId":120857,"resultsCount":8,"campaigns":[28],"substitutions":{"category":["cm9vdA","TcO2YmVsPlRpc2NoZQ"],"price":19.9},"staticFilters":{"excluded":[{"column":"brand","values":["Nike","Puma"]}],"included":[{"column":"brand","values":["Nike","Puma"]}]},"dynamicFilters":[{"column":"product_type","values":["cm9vdA","TcO2YmVsPlRpc2NoZQ"]}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.vviinn.com/similar-products \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "requestId": "6edf9d4d-60e8-49f3-b120-e89d728b8a89", "productId": 120857, "resultsCount": 8, "campaigns": [ 28 ], "substitutions": { "category": [ "cm9vdA", "TcO2YmVsPlRpc2NoZQ" ], "price": 19.9 }, "staticFilters": { "excluded": [ { "column": "brand", "values": [ "Nike", "Puma" ] } ], "included": [ { "column": "brand", "values": [ "Nike", "Puma" ] } ] }, "dynamicFilters": [ { "column": "product_type", "values": [ "cm9vdA", "TcO2YmVsPlRpc2NoZQ" ] } ] }'This endpoint allows to discover products similar to the source product, usually chosen by a user. The response contains a list of similarities for each product.
Authorizations
Section titled “Authorizations”Request Body
Section titled “Request Body”Similar Products request body
object
Example
6edf9d4d-60e8-49f3-b120-e89d728b8a89Example
120857Returns less than or equal to the campaign’s defined results
Example
8List of campaign ids
object
Each item describes a category path that should be used instead of the product’s actual category paths
Example
[ "cm9vdA", "TcO2YmVsPlRpc2NoZQ"]Example
19.9The static filters are predefined parameters that set the initial scope for the data retrieval process.
These filters are configured to extract a broad, meaningful set of results based on your criteria.
Once applied, they help in reducing the dataset to a manageable and relevant subset before any further, more granular filtering occurs via dynamicFilters.
object
Each item describes a column and values from that column that should be excluded from the result set
object
Example
brandExample
[ "Nike", "Puma"]Each item describes a column and values from that column that should be included in the result set
object
Example
brandExample
[ "Nike", "Puma"]The dynamic filters are parameters that refine the already narrowed down dataset from the staticFilters based on real-time request criteria.
These filters are flexible and can be adjusted dynamically to specific user queries or requirements, allowing for further granular filtering.
They provide a more precise result based on the user’s immediate needs.
object
Example
product_typeEach item describes a category path that should be used instead of the product’s actual category paths
Example
[ "cm9vdA", "TcO2YmVsPlRpc2NoZQ"]Example
[ "Nike", "Puma"]The interval object that is defined by a [start, end).
object
Example
[ "black > #1A1A1A", "beige > #C7B3A8"]Example
[ "black", "beige"]Responses
Section titled “Responses”OK
object
object
object
This field is superseded by the entity type and therefore deprecated.
The API usually returns products; it can also return entities representing something else.
To enable different handling of these entities, the API uses an entity-type to distinguish between them, namely:
- A
productentity represents a product in the catalog. - A
contententity contains information relevant to a user, e.g., trends, opening hours. - A
listentity comprises a collection of distinguishable items, e.g., a category page.
Link to the product detail page
object
object
object
object
The base price per measure is derived by adjusting the product’s total cost to a standardized unit of measurement, making it easier to compare products of varying volumes.
object
The base price per measure is derived by adjusting the product’s total cost to a standardized unit of measurement, making it easier to compare products of varying volumes.
object
object
object
object
object
This field is superseded by the entity type and therefore deprecated.
The API usually returns products; it can also return entities representing something else.
To enable different handling of these entities, the API uses an entity-type to distinguish between them, namely:
- A
productentity represents a product in the catalog. - A
contententity contains information relevant to a user, e.g., trends, opening hours. - A
listentity comprises a collection of distinguishable items, e.g., a category page.
Link to the product detail page
object
object
object
object
The base price per measure is derived by adjusting the product’s total cost to a standardized unit of measurement, making it easier to compare products of varying volumes.
object
The base price per measure is derived by adjusting the product’s total cost to a standardized unit of measurement, making it easier to compare products of varying volumes.
object
object
object
object
object
object
object
In a category tree, a category path identifies a category of the tree. The API expects and returns each category path only in encoded form.
A category path is a sequence category labels, separated by the > character.
Whitespace around the category labels is ignored.
If the > character is part of a category label, it must be escaped with %3E.
The root node has no label and is omitted in a category path.
To represent the root node, use root as the sole label instead.
Consider the following category tree:
.
├── Furniture
│ ├── Benches
│ └── Cabinets & Storage
└── Home & Garden
├── Plants
├── Wood Stoves
└── Fish Pond (<><)That contains the following category paths:
rootFurnitureFurniture > BenchesFurniture > Cabinets & StorageHome & GardenHome & Garden > PlantsHome & Garden > Wood StovesHome & Garden > Fish Pond (<%3E<)
Category paths are transmitted in encoded form. To this end, we use the Base64-URL encoding without any padding. The category paths above are encoded as follows:
cm9vdARnVybml0dXJlRnVybml0dXJlID4gQmVuY2hlcwRnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdlSG9tZSAmIEdhcmRlbgSG9tZSAmIEdhcmRlbiA-IFBsYW50cwSG9tZSAmIEdhcmRlbiA-IFdvb2QgU3RvdmVzSG9tZSAmIEdhcmRlbiA-IEZpc2ggUG9uZCAoPCUzRTwp
On Linux, the basenc command can be used to encode category paths:
echo -n 'Furniture > Cabinets & Storage' | basenc -w0 --base64url
# returns: RnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdl
echo -n 'RnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdl' | basenc -d -w0 --base64url
# returns: Furniture > Cabinets & Storageobject
object
object
object
The interval object that is defined by a [start, end).
object
The interval object that is defined by a [start, end).
object
object
object
The interval object that is defined by a [start, end).
object
object
object
The interval object that is defined by a [start, end).
object
object
A rectangle is defined by the position of its top-left corner and its side lengths.
Each value is relative to an image’s dimensions, i.e., they are in the range [0, 1].
The top-left corner is defined to be at (0, 0), the bottom-right corner at (1, 1).
object
The relative distance to the left edge of the image
The relative distance to the top edge of the image
The width relative to the image’s width
The height relative to the image’s height
object
The URL to which the user should be redirected.
object
object
In a category tree, a category path identifies a category of the tree. The API expects and returns each category path only in encoded form.
A category path is a sequence category labels, separated by the > character.
Whitespace around the category labels is ignored.
If the > character is part of a category label, it must be escaped with %3E.
The root node has no label and is omitted in a category path.
To represent the root node, use root as the sole label instead.
Consider the following category tree:
.
├── Furniture
│ ├── Benches
│ └── Cabinets & Storage
└── Home & Garden
├── Plants
├── Wood Stoves
└── Fish Pond (<><)That contains the following category paths:
rootFurnitureFurniture > BenchesFurniture > Cabinets & StorageHome & GardenHome & Garden > PlantsHome & Garden > Wood StovesHome & Garden > Fish Pond (<%3E<)
Category paths are transmitted in encoded form. To this end, we use the Base64-URL encoding without any padding. The category paths above are encoded as follows:
cm9vdARnVybml0dXJlRnVybml0dXJlID4gQmVuY2hlcwRnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdlSG9tZSAmIEdhcmRlbgSG9tZSAmIEdhcmRlbiA-IFBsYW50cwSG9tZSAmIEdhcmRlbiA-IFdvb2QgU3RvdmVzSG9tZSAmIEdhcmRlbiA-IEZpc2ggUG9uZCAoPCUzRTwp
On Linux, the basenc command can be used to encode category paths:
echo -n 'Furniture > Cabinets & Storage' | basenc -w0 --base64url
# returns: RnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdl
echo -n 'RnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdl' | basenc -d -w0 --base64url
# returns: Furniture > Cabinets & Storageobject
object
object
object
In a category tree, a category path identifies a category of the tree. The API expects and returns each category path only in encoded form.
A category path is a sequence category labels, separated by the > character.
Whitespace around the category labels is ignored.
If the > character is part of a category label, it must be escaped with %3E.
The root node has no label and is omitted in a category path.
To represent the root node, use root as the sole label instead.
Consider the following category tree:
.
├── Furniture
│ ├── Benches
│ └── Cabinets & Storage
└── Home & Garden
├── Plants
├── Wood Stoves
└── Fish Pond (<><)That contains the following category paths:
rootFurnitureFurniture > BenchesFurniture > Cabinets & StorageHome & GardenHome & Garden > PlantsHome & Garden > Wood StovesHome & Garden > Fish Pond (<%3E<)
Category paths are transmitted in encoded form. To this end, we use the Base64-URL encoding without any padding. The category paths above are encoded as follows:
cm9vdARnVybml0dXJlRnVybml0dXJlID4gQmVuY2hlcwRnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdlSG9tZSAmIEdhcmRlbgSG9tZSAmIEdhcmRlbiA-IFBsYW50cwSG9tZSAmIEdhcmRlbiA-IFdvb2QgU3RvdmVzSG9tZSAmIEdhcmRlbiA-IEZpc2ggUG9uZCAoPCUzRTwp
On Linux, the basenc command can be used to encode category paths:
echo -n 'Furniture > Cabinets & Storage' | basenc -w0 --base64url
# returns: RnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdl
echo -n 'RnVybml0dXJlID4gQ2FiaW5ldHMgJiBTdG9yYWdl' | basenc -d -w0 --base64url
# returns: Furniture > Cabinets & Storageobject
object
object
Example
{ "requestId": "6edf9d4d-60e8-49f3-b120-e89d728b8a89", "data": { "sourceProduct": { "kind": "product", "entityType": "product", "groupId": "55fc5f71d6362321cb93b82b387e2f32", "productId": "55fc5f71d6362321cb93b82b387e2f32", "title": "Livingwalls Fototapete Walls by Patel iconic 3", "deeplink": "http://mainUrl/site/5/product/55fc5f71d6362321cb93b82b387e2f32/details", "brand": "Fender", "productType": "guitar", "image": { "original": "http://mainUrl/image.jpg", "thumbnail": "http://mainUrl/thumbnail-image.jpg" }, "images": [ { "original": "http://mainUrl/image.jpg", "thumbnail": "http://mainUrl/thumbnail-image.jpg" } ], "price": { "actual": 19.9, "sale": 19.9 }, "basePrice": { "actual": { "price": 15.92, "quantity": 100, "measure": "ml" }, "sale": { "price": 15.92, "quantity": 100, "measure": "ml" } }, "energyEfficiencyClass": "A+++", "minEnergyEfficiencyClass": "A+++", "maxEnergyEfficiencyClass": "A+++", "energyCertifications": [ { "certificationClass": "A+++", "classRange": { "min": "A+++", "max": "A+++" } } ] }, "products": [ { "kind": "product", "entityType": "product", "groupId": "55fc5f71d6362321cb93b82b387e2f32", "productId": "55fc5f71d6362321cb93b82b387e2f32", "title": "Livingwalls Fototapete Walls by Patel iconic 3", "deeplink": "http://mainUrl/site/5/product/55fc5f71d6362321cb93b82b387e2f32/details", "brand": "Fender", "productType": "guitar", "image": { "original": "http://mainUrl/image.jpg", "thumbnail": "http://mainUrl/thumbnail-image.jpg" }, "images": [ { "original": "http://mainUrl/image.jpg", "thumbnail": "http://mainUrl/thumbnail-image.jpg" } ], "price": { "actual": 19.9, "sale": 19.9 }, "basePrice": { "actual": { "price": 15.92, "quantity": 100, "measure": "ml" }, "sale": { "price": 15.92, "quantity": 100, "measure": "ml" } }, "energyEfficiencyClass": "A+++", "minEnergyEfficiencyClass": "A+++", "maxEnergyEfficiencyClass": "A+++", "energyCertifications": [ { "certificationClass": "A+++", "classRange": { "min": "A+++", "max": "A+++" } } ] } ] }, "interactions": { "dynamicFilters": [ { "type": "categorical", "column": "product_type", "label": "Product Type", "isPrimary": true, "values": [ { "value": [ "RnVybml0dXJl", "SG9tZSAmIEdhcmRlbg" ], "label": "Tische", "active": true, "selected": false } ] } ], "suggestedSearchAreas": [ { "rectangle": { "left": 0.1728, "top": 0.3641, "width": 0.4575, "height": 0.2917 } } ], "redirect": { "url": "https://www.example.com/some-category" } }, "substitutions": [ { "column": "product_type", "value": { "value": [ "RnVybml0dXJl", "SG9tZSAmIEdhcmRlbg" ], "label": "Tische" } } ]}Generic Error
object
Example
{ "message": "Generic Error"}Authentication Error
Example
{ "message": "Authentication Error"}Authorization Error
Example
{ "message": "Authorization Error"}Generic Error
object
Example
{ "message": "Generic Error"}Generic Error
object
Example
{ "message": "Generic Error"}