Skip to main content

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.