API
Authentication
For all API requests, include a header called x-visidea-token
. The value should be the public token, which you can retrieve from the Visidea dashboard under the settings section.
Example:
x-visidea-token: [public_token]
Settings
Get Website Settings
To retrieve the settings for your website, make the following request:
GET https://api.visidea.ai/api/settings
Response Example:
{
"home": [
{
"show": true,
"algo": "user",
"title": "Recommended for you",
"n": "12",
"show_after": ""
}
],
"product": [
{
"show": true,
"algo": "similarity",
"title": "You may also like",
"n": "12",
"show_after": "",
"query": ""
}
],
"cart": [
{
"show": true,
"algo": "user",
"title": "Recommended for you",
"n": 12,
"show_after": ""
}
],
"order": [
{
"show": true,
"algo": "user",
"title": "Recommended for user",
"n": 12,
"show_after": ""
}
],
"css": "",
"has_visualsearch": true,
"has_semanticsearch": true,
"currency": "EUR",
"currency_format": "amountwithcomma_currency",
"visualsearch_show_after": ".css_handle",
"visualsearch_image": "",
"visualsearch_displaygenderfilter": true,
"visualsearch_displaypricefilter": true,
"visualsearch_displaycategoryfilter": true,
"visualsearch_displaybrandfilter": true,
"semanticsearch_bind": ".css_handle"
}
Response Explanation:
For each section of the website (home, product detail, cart, and order/checkout), the response includes the following settings:
- show: Whether the carousel is displayed.
- algo: The algorithm used (e.g., "user" or "similarity").
- title: The title to display above the carousel.
- n: The number of products to display in the carousel.
- show_after: The CSS handle where the carousel should appear.
Additional settings include:
- css: Custom CSS to be injected into the website.
- has_visualsearch: Boolean flag indicating if the Visual Search feature is enabled.
- has_semanticsearch: Boolean flag indicating if the Semantic Search feature is enabled.
- currency: The currency used on the website (e.g., "EUR").
- currency_format: The format for displaying currency (e.g., "amountwithcomma_currency").
- visualsearch_show_after: The CSS handle after which the Visual Search icon should be inserted.
- visualsearch_image: The image displayed in the Visual Search lightbox.
- visualsearch_displaygenderfilter: Boolean flag to enable or disable the gender filter in the lightbox.
- visualsearch_displaypricefilter: Boolean flag to enable or disable the price filter in the lightbox.
- visualsearch_displaycategoryfilter: Boolean flag to enable or disable the category filter in the lightbox.
- visualsearch_displaybrandfilter: Boolean flag to enable or disable the brand filter in the lightbox.
- semanticsearch_bind: The CSS handle for the element that triggers the Semantic Search lightbox when clicked.
Recommendations API
Request recommendations
To request product recommendations for a specific section of your website, send the following request:
POST https://api.visidea.ai/api/recommend
Request Payload:
{
"algo": "user",
"n_rec": 12,
"session_id": "[session_id]",
"user_id": "[user_id]"
}
Request Parameters:
- algo Specifies the recommendation algorithm to use. Available options include:
- user: Collaborative filtering algorithm (based on user behavior).
- pop: Popular items algorithm (based on item popularity).
- history: Last-seen items algorithm.
- similarity: Visual similarity algorithm.
- item: Frequently bought together algorithm. For more information on these algorithms, refer to the algorithms description page.
- n_rec Number of recommendations to retrieve.
- session_id ID of the user session.
- user_id ID of the user.
Response Example:
[
{
"id": "62e1e1733425d70fa86a663f",
"item_id": "29328",
"name": "Trousers",
"brand_id": 5397,
"brand_name": "DIESEL",
"page_ids": [
3,
5,
15,
308,
50
],
"page_names": [
"Products",
"WOMAN",
"SALES",
"Clothing",
"Trousers"
],
"category_id": 50,
"category_name": "Trousers",
"gender": "Woman",
"price": 250,
"market_price": 175,
"discount": 30,
"url": "https://www.website.com/en/products/index/diesel-trousers-29328-50/",
"images": [
"https://www.website.com/contents/imgs/products/0_67158-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67159-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67160-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67161-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67163-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67164-diesel-trousers.jpg"
],
"tags": [
"Tag 1",
"Tag 1",
"Tag 3"
]
},
...
]
Response Breakdown:
The response is an array of recommended items. Each item includes:
- id: Internal item ID.
- item_id: External product ID.
- name: Product name.
- brand_id: Brand identifier.
- brand_name: Brand name.
- page_ids: Array of page identifiers where the item is displayed.
- page_names: Names of the associated pages.
- category_id: Product category ID.
- category_name: Product category name.
- gender: Gender for which the product is intended.
- price: Current product price.
- market_price: Original market price before discount.
- discount: Discount percentage applied.
- url: URL to the product page.
- images: Array of image URLs for the product.
- tags: Additional tags associated with the product.
Semantic Search API
Search Request
To perform a search for a specific query, make the following request:
POST https://api.visidea.ai/api/textsearch
Request Payload:
{
"query": "[query]",
"limit": [limit],
"offset": [offset],
"language": "[language]",
"session_id": "[session_id]",
"user_id": "[user_id]",
"filters": "{ brand_id: [brand_id], page_id: [page_id], attributes.[attribute]: '[val]', price: { gte: 100, lt: 200 }, ... }"
}
Request Parameters:
- query: The search query string.
- limit: Number of results to retrieve.
- offset: The first element to retrieve from.
- language: The language of the query/results.
- session_id: ID of the user session.
- user_id: ID of the user.
- filters: The filters to limit the results.
Range Filters
You can apply range filters with the following operators:
- gte: Greater than or equal to
- lte: Less than or equal to
- gt: Greater than
- lt: Less than
Response Example:
{
"results": 123,
"data": [
{
"id": "62e1e1733425d70fa86a663f",
"item_id": "29328",
"name": "Trousers",
"brand_id": 5397,
"brand_name": "DIESEL",
"page_ids": [
3,
5,
15,
308,
50
],
"page_names": [
"Products",
"WOMAN",
"SALES",
"Clothing",
"Trousers"
],
"category_id": 50,
"category_name": "Trousers",
"gender": "Woman",
"price": 250,
"market_price": 175,
"discount": 30,
"url": "https://www.website.com/en/products/index/diesel-trousers-29328-50/",
"images": [
"https://www.website.com/contents/imgs/products/0_67158-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67159-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67160-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67161-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67163-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67164-diesel-trousers.jpg"
],
"tags": [
"Tag 1",
"Tag 1",
"Tag 3"
],
"attributes": {
"attribute1": "Val 1",
"attribute2": "Val 2",
"attribute3": "Val 3"
}
},
...
]
}
Response Breakdown:
The response is an object containing the following:
- results: The total number of results.
- data: An array of paginated recommended items.
Each item includes:
- id: Internal item ID.
- item_id: External product ID.
- name: Product name.
- brand_id: Brand identifier.
- brand_name: Brand name.
- page_ids: Array of page identifiers where the item is displayed.
- page_names: Names of the associated pages.
- category_id: Product category ID.
- category_name: Product category name.
- gender: Gender for which the product is intended.
- price: Current product price.
- market_price: Original market price before discount.
- discount: Discount percentage applied.
- url: URL to the product page.
- images: Array of image URLs for the product.
- tags: Additional tags associated with the product.
- attributes: Additional attributes associated with the product.
Semantic Search Filters API
Filter Request
To retrieve the filters available for a specific query, make the following request:
POST https://api.visidea.ai/api/textsearch/filters
Request Payload:
{
"query": "[query]",
"language": "[language]",
"session_id": "[session_id]",
"user_id": "[user_id]",
"filters": "{ brand_id: [brand_id], page_id: [page_id], attributes.[attribute]: '[val]', price: { gte: 100, lt: 200 }, ... }"
}
Request Parameters:
- query: The search query string.
- language: The language of the query/results.
- session_id: ID of the user session.
- user_id: ID of the user.
- filters: The filters parameters should be a json formatted as a string.
Range Filters
You can apply range filters with the following operators:
- gte: Greater than or equal to
- lte: Less than or equal to
- gt: Greater than
- lt: Less than
Response Example:
{
"brand_names": [
"Dolce & Gabbana",
"Givenchy",
"Gucci",
"Saint Laurent"
],
"brand_ids": [
41,
242,
198,
63
],
"page_names": [
"Products",
"WOMAN",
"SALES",
"Clothing",
"Jeans",
"T-shirts",
"Trousers"
],
"page_ids": [
3,
5,
15,
61,
308,
91,
50
],
"tags": [
"Tag 1",
"Tag 1",
"Tag 3"
],
"attributes": {
"attribute1": [
"val1",
"val2",
"val3",
],
"attribute2": [
"val1",
"val2",
"val3",
]
}
}
Response Breakdown:
The response is an object containing the following:
- brand_names: An array containing the names of the brands.
- brand_ids: An array containing the corresponding numeric IDs for each brand.
- page_names: An array containing the names of the pages.
- page_ids: An array containing the corresponding numeric IDs for each page.
- tags: An array containing the tags associated with the results.
- attributes: An object containing key-value pairs representing attributes and their respective values.
Visual Search API
Search Request
To initiate a visual search using an image, send a POST request to the following endpoint:
POST https://api.visidea.ai/api/visualsearch
Request Payload:
{
"img": "data:image/jpeg;base64,...",
"session_id": "[session_id]",
"user_id": "[user_id]"
}
Request Parameters:
- img The image in base64-encoded format.
- session_id ID of the user session.
- user_id ID of the user.
Response Example:
{
"detections": [
{
"xcenter": 810,
"ycenter": 1086,
"width": 1211,
"height": 743,
"confidence": 0.9591711759567261,
"class": 24,
"name": "",
"embedding": [...]
}
]
}
Response Breakdown:
The response contains an array of object detections. Each detection provides the following information:
- xcenter: X-coordinate of the bounding box center (in pixels).
- ycenter: Y-coordinate of the bounding box center (in pixels).
- width: Width of the bounding box (in pixels).
- height: Height of the bounding box (in pixels).
- confidence: The confidence level for the detected object (ranging from 0 to 1).
- class: The class ID representing the object type.
- name: The name of the object class (may be empty).
- embedding: A numerical representation (vector) of the object for further processing or comparisons.
Visual Recommend API
Search Request
To retrieve recommendations based on a specific embedding, send a POST request to the following endpoint:
POST https://api.visidea.ai/api/visualrecommend
Request Payload:
{
"img": [embedding],
"detected_class": "[detected_class]",
"n_rec": 12,
"session_id": "[session_id]",
"user_id": "[user_id]"
}
Request Parameters:
- img The embedding generated from the Visual Search API response.
- detected_class The object class detected by the Visual Search API.
- n_rec The number of recommendations to return.
- session_id ID of the user session.
- user_id ID of the user.
Response Example:
[
{
"id": "62e1e1733425d70fa86a663f",
"item_id": "29328",
"name": "Trousers",
"brand_id": 5397,
"brand_name": "DIESEL",
"page_ids": [
3,
5,
15,
308,
50
],
"page_names": [
"Products",
"WOMAN",
"SALES",
"Clothing",
"Trousers"
],
"category_id": 50,
"category_name": "Trousers",
"gender": "Woman",
"price": 250,
"market_price": 175,
"discount": 30,
"url": "https://www.website.com/en/products/index/diesel-trousers-29328-50/",
"images": [
"https://www.website.com/contents/imgs/products/0_67158-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67159-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67160-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67161-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67163-diesel-trousers.jpg",
"https://www.website.com/contents/imgs/products/0_67164-diesel-trousers.jpg"
],
"tags": [
"Tag 1",
"Tag 1",
"Tag 3"
]
},
...
]
Response Breakdown:
The response is an array of recommended items. Each item includes:
- id: Internal item ID.
- item_id: External product ID.
- name: Product name.
- brand_id: Brand identifier.
- brand_name: Brand name.
- page_ids: Array of page identifiers where the item is displayed.
- page_names: Names of the associated pages.
- category_id: Product category ID.
- category_name: Product category name.
- gender: Gender for which the product is intended.
- price: Current product price.
- market_price: Original market price before discount.
- discount: Discount percentage applied.
- url: URL to the product page.
- images: Array of image URLs for the product.
- tags: Additional tags associated with the product.