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]

Additional header

For all API requests, include a header called content-type with the value application/json.

Example:

content-type: application/json

User/session management

For certain API requests, it is required to provide a user_id and/or a session_id.

The user_id is the identifier generated by the CMS. If the user has not logged in and a user_id is not yet available, a UUID can be used as a temporary identifier until the CMS provides the corresponding user_id. When the user_id changes, the merge_user endpoint must be called (see below).
The session_id is the session identifier generated by the CMS. If the CMS does not provide a session_id, a UUID can be used as a temporary session identifier for tracking purposes.

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": str,
    "n_rec": int,
    "session_id": str,
    "user_id": str,
    "item_id": str
}

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.
item_id ID of the item (if needed by the algorithm).

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.

Filtering specifications

Searches can be filtered in order to narrow the search space of products considered as possible relevant results. We use a MongoDB-like language specified as follows.

Basic Syntax

The query language uses a key-value pair format, similar to JSON:

{attribute: value, attribute: value, ...}

Multiple conditions are separated by commas.

Filterable attributes

The following set of keys can be used:

brand_name: str
brand_id: str
page_names: List[str]
page_ids: List[str]
page_urls: List[str]
tags: List[str]
attributes: JSON -> use python-style references, such as attributes[\"key\"] to refer to the contents of the json object

Available filters

1. Simple Equality

For exact matches:

{attribute: value}

Example:

{color: "blue"}

2. Comparison Operators

Use comparison operators for range queries:

gt: Greater than
gte: Greater than or equal to
lt: Less than
lte: Less than or equal to

Syntax:

{attribute: {operator: value}}

Examples:

{price: {gt: 100}}
{age: {gte: 18, lt: 65}}

3. List of Values (IN)

To match any value in a list:

{attribute: [value1, value2, ...]}

Example:

{brand: ["Nike", "Adidas", "Puma"]}

4. String Prefix Match (LIKE)

For string prefix matching:

{attribute: {like: "prefix%"}}

Example:

{name: {like: "John%"}}

Combining Multiple Conditions

You can combine multiple conditions in a single query. All conditions are implicitly combined with AND logic.

Example:

{price: {gte: 50, lt: 100}, brand: ["Nike", "Adidas"], color: "red"}

This query translates to: price is greater than or equal to 50 AND less than 100 AND brand is either Nike or Adidas AND color is red.

Important Notes

String values should always be enclosed in double quotes.
Numeric values do not need quotes.
The like operator only supports prefix matching (ending with %).
Nested objects or arrays (except for the IN operation) are not supported.
All conditions in a single query are combined with AND logic. OR logic must be handled at the application level by combining multiple queries.

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": str,
    "limit": int,
    "offset": int,
    "language": str,
    "session_id": str,
    "user_id": str,
    "filters": str,
    "threshold": float
}

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 apply at search time. For more details, refer to the Filtering specifications section.
threshold: The confidence/threshold value of how results can differ from exact match (values from 0.7 to 1 are optimal). Greater values means more results.

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"
         ],
         "attributes": {
            "attribute1": "Val 1",
            "attribute2": "Val 2",
            "attribute3": "Val 3"
         }
      },
      ...
   ]
}

Response Breakdown:

The response is a list of JSON objects with the following attributes:

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.

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": str,
    "language": str,
    "session_id": str,
    "user_id": str,
    "filters": str,
    "threshold": float,
    "n_cand": int
}

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. For more details, refer to the Filtering specifications section.
threshold: The confidence/threshold value of how results can differ from exact match (values from 0.7 to 1 are optimal). Greater values means more results.
n_cand: How many maximum element should be scanned.

Response Example:

{
   "results": 123,
   "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:

results: total number of items retrieved for the query
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": str,
    "session_id": str,
    "user_id": str
}

Request Parameters:

img The image in base64-encoded format, eg: "data:image/jpeg;base64,...".
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.

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": List[float],
    "detected_class": int,
    "n_rec": int,
    "session_id": str,
    "user_id": str
}

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.

Merge Users API

Search Request

When the user_id of the current user changes (e.g., during a login action), a POST request must be sent to the following endpoint:

POST https://api.visidea.ai/api/merge_users

Request Payload:

{
    "old_user_id": "[old_user_id]",
    "new_user_id": "[new_user_id]"
}

Request Parameters:

old_user_id ID of the old user.
new_user_id ID of the new user.

Response Example:

{
    "status": "ok"
}

API

Authentication​

Additional header​

User/session management​

Settings​

Get Website Settings​

Response Example:​

Response Explanation:​

Recommendations API​

Request recommendations​

Request Payload:​

Request Parameters:​

Response Example:​

Response Breakdown:​

Filtering specifications​

Basic Syntax​

Filterable attributes​

Available filters​

1. Simple Equality​

2. Comparison Operators​

3. List of Values (IN)​

4. String Prefix Match (LIKE)​

Combining Multiple Conditions​

Important Notes​

Semantic Search API​

Search Request​

Request Payload:​

Request Parameters:​

Response Example:​

Response Breakdown:​

Semantic Search Filters API​

Filter Request​

Request Payload:​

Request Parameters:​

Response Example:​

Response Breakdown:​

Visual Search API​

Search Request​

Request Payload:​

Request Parameters:​

Response Example:​

Response Breakdown:​

Visual Recommend API​

Search Request​

Request Payload:​

Request Parameters:​

Response Example:​

Response Breakdown:​

Merge Users API​

Search Request​

Request Payload:​

Request Parameters:​

Response Example:​

Authentication

Additional header

User/session management

Settings

Get Website Settings

Response Example:

Response Explanation:

Recommendations API

Request recommendations

Request Payload:

Request Parameters:

Response Example:

Response Breakdown:

Filtering specifications

Basic Syntax

Filterable attributes

Available filters

1. Simple Equality

2. Comparison Operators

3. List of Values (IN)

4. String Prefix Match (LIKE)

Combining Multiple Conditions

Important Notes

Semantic Search API

Search Request

Request Payload:

Request Parameters:

Response Example:

Response Breakdown:

Semantic Search Filters API

Filter Request

Request Payload:

Request Parameters:

Response Example:

Response Breakdown:

Visual Search API

Search Request

Request Payload:

Request Parameters:

Response Example:

Response Breakdown:

Visual Recommend API

Search Request

Request Payload:

Request Parameters:

Response Example:

Response Breakdown:

Merge Users API

Search Request

Request Payload:

Request Parameters:

Response Example: