Skip to main content

API

Required Headers​

All API requests must include the following headers:

  • x-visidea-token: Your public token, available in the Visidea dashboard under the settings section.
  • content-type: Must be set to application/json.

Example:

x-visidea-token: [public_token]
content-type: application/json

User and Session Management​

Some API requests require you to provide a user_id and/or a session_id:

  • user_id: This is the unique identifier for the user, typically generated by your CMS. If the user is not logged in and a user_id is not available, you can generate a temporary UUID to identify the user until the CMS assigns a permanent user_id. When the user_id changes (for example, after a login), you must call the merge_users endpoint to associate the previous activity with the new user (see below).

  • session_id: This is the unique identifier for the user's session, usually generated by your CMS. If your CMS does not provide a session_id, you can generate a temporary UUID to track the session.

Using consistent user_id and session_id values ensures accurate tracking and personalized recommendations across user sessions.

Settings​

Retrieve Website Settings​

To obtain your website’s current configuration, send the following request:

GET https://api.visidea.ai/api/settings

This endpoint returns all relevant settings for your Visidea integration.

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:​

The response provides configuration settings for each main section of your website—such as home, product detail, cart, and order/checkout. For each section, you’ll find:

  • show: Indicates whether the product carousel is visible.
  • algo: The recommendation algorithm to use (e.g., "user", "similarity").
  • title: The heading displayed above the carousel.
  • n: The number of products to show in the carousel.
  • show_after: The CSS selector specifying where to insert the carousel.

Additional global settings include:

  • css: Custom CSS rules to inject into your site.
  • has_visualsearch: Whether the Visual Search feature is enabled (true or false).
  • has_semanticsearch: Whether the Semantic Search feature is enabled (true or false).
  • currency: The currency code used on your website (e.g., "EUR").
  • currency_format: The format for displaying currency values (e.g., "amountwithcomma_currency").
  • visualsearch_show_after: CSS selector indicating where to place the Visual Search icon.
  • visualsearch_image: The image shown in the Visual Search lightbox.
  • visualsearch_displaygenderfilter: Enables or disables the gender filter in the Visual Search lightbox.
  • visualsearch_displaypricefilter: Enables or disables the price filter in the Visual Search lightbox.
  • visualsearch_displaycategoryfilter: Enables or disables the category filter in the Visual Search lightbox.
  • visualsearch_displaybrandfilter: Enables or disables the brand filter in the Visual Search lightbox.
  • semanticsearch_bind: CSS selector for the element that triggers the Semantic Search lightbox when clicked.

These settings allow you to customize the appearance and behavior of Visidea features on your website.

Recommendations API​

Requesting Recommendations​

To fetch product recommendations for a specific section of your website, send a POST request to:

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

Include the appropriate payload and headers as described above. This endpoint returns a list of recommended products tailored to the provided context (such as user, session, or item).

Request Payload:​

{
    "algo": str,
    "n_rec": int,
    "session_id": str,
    "user_id": str,
    "item_id": str
}

Request Parameters:​

  • algo: Defines which recommendation algorithm to use. Available options:
    • user: Collaborative filtering (personalized recommendations based on user behavior).
    • pop: Popular items (recommends trending or most-viewed products).
    • history: Last-seen items (shows products recently viewed by the user).
    • new: New arrivals (highlights the latest products).
    • similarity: Visual similarity (suggests products visually similar to a given item).
    • item: Frequently bought together (recommends items often purchased with the current product).

For detailed descriptions of each algorithm, see the algorithms description page.

  • n_rec: The number of recommendations to return.
  • session_id: Unique identifier for the user session.
  • user_id: Unique identifier for the user.
  • item_id: Product ID to base recommendations on (required for certain algorithms, such as "similarity" or "item").

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 returns an array of recommended products. Each product object contains the following fields:

  • id: Internal identifier for the item.
  • item_id: External product identifier.
  • name: Name of the product.
  • brand_id: Unique identifier for the brand.
  • brand_name: Name of the brand.
  • page_ids: Array of page IDs where the product appears.
  • page_names: Names of the associated pages.
  • category_id: Identifier for the product category.
  • category_name: Name of the product category.
  • gender: Intended gender for the product (if applicable).
  • price: Current price of the product.
  • market_price: Original price before any discounts.
  • discount: Discount percentage applied to the product.
  • url: Direct URL to the product page.
  • images: Array of image URLs for the product.
  • tags: Additional tags or attributes associated with the product.

This structure provides all the necessary information to display recommended products on your frontend.

Filtering Specifications​

You can filter searches to narrow down the set of products considered as relevant results. Visidea uses a MongoDB-like query language for filtering.

Basic Syntax​

Filters are expressed as key-value pairs in a JSON-like format:

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

Separate multiple conditions with commas. All conditions are combined using AND logic.

Filterable Attributes​

You can filter using the following attributes:

  • brand_name: str — Name of the brand.
  • brand_id: str — Brand identifier.
  • page_names: List[str] — Names of the pages where the product appears.
  • page_ids: List[str] — Page identifiers.
  • page_urls: List[str] — URLs of the pages.
  • tags: List[str] — Tags associated with the product.
  • attributes: JSON — Use Python-style references (e.g., attributes["key"]) to filter by specific keys within the attributes object.

This flexible filtering system allows you to target exactly the products you want to include in your search results.

Available Filters​

1. Simple Equality​

Use simple key-value pairs to filter for exact matches:

{attribute: value}

Example:

{color: "blue"}

2. Comparison Operators​

Apply range-based filtering with comparison operators:

  • 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)​

Filter for items matching any value in a list:

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

Example:

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

4. String Prefix Match (LIKE)​

Match items where a string attribute starts with a specific prefix:

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

Example:

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

Combining Multiple Conditions​

You can specify multiple conditions in a single filter object. All conditions are combined using AND logic.

Example:

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

This query means: 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​

  1. Enclose all string values in double quotes.
  2. Numeric values do not require quotes.
  3. The like operator supports only prefix matching (must end with %).
  4. Nested objects or arrays (except for the IN operation) are not supported.
  5. All conditions are combined with AND logic. To implement OR logic, send multiple queries at the application level.

Semantic Search API​

Search Request​

To perform a semantic search for products based on a user query, send a POST request to:

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
}

Parameter Details​

  • query: The search query string entered by the user.
  • limit: Maximum number of results to return.
  • offset: The starting index for the results (useful for pagination).
  • language: Language code for the query and results (e.g., "en", "it").
  • session_id: Unique identifier for the user session.
  • user_id: Unique identifier for the user.
  • filters: Optional filters to refine the search results. See Filtering specifications for details.
  • threshold: Confidence threshold for result similarity (range: 0 to 1). Lower values return more results; values between 0.1 and 0.5 are recommended for optimal relevance.

This endpoint returns a list of products that best match the semantic meaning of the provided query, allowing for advanced and flexible product discovery.

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 consists of an array of product objects, each containing the following fields:

  • id: Internal identifier for the item.
  • item_id: External product identifier.
  • name: Name of the product.
  • brand_id: Unique identifier for the brand.
  • brand_name: Name of the brand.
  • page_ids: Array of page IDs where the product appears.
  • page_names: Names of the associated pages.
  • category_id: Identifier for the product category.
  • category_name: Name of the product category.
  • gender: Intended gender for the product (if applicable).
  • price: Current price of the product.
  • market_price: Original price before any discounts.
  • discount: Discount percentage applied to the product.
  • url: Direct URL to the product page.
  • images: Array of image URLs for the product.
  • tags: List of tags or labels associated with the product.
  • attributes: Key-value pairs representing additional product attributes (such as color, size, material, etc.).

This structure provides all the necessary details to display and describe recommended products in your frontend application.

Semantic Search Filters API​

Retrieving Available Filters​

To get the list of filters relevant to a specific search query, send a POST request to:

POST https://api.visidea.ai/api/textsearch/filters

This endpoint returns the available filter options that can be applied to refine your semantic search results.

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: Language code for the query and results (e.g., "en", "it").
  • session_id: Unique identifier for the user session.
  • user_id: Unique identifier for the user.
  • filters: Filters to apply, provided as a JSON-formatted string. See the Filtering specifications for details.
  • threshold: Similarity threshold for matching results (recommended range: 0.7 to 1). Higher values return more relevant results.
  • n_cand: Maximum number of candidate items to scan during filtering.

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 with the following fields:

  • results: The total number of items matching the query.
  • brand_names: Array of brand names present in the results.
  • brand_ids: Array of numeric brand IDs corresponding to the brands.
  • page_names: Array of page names where the items appear.
  • page_ids: Array of numeric page IDs associated with the results.
  • tags: Array of tags found among the results.
  • attributes: An object containing attribute names as keys and arrays of possible values as values.

This structure provides all available filter options for the current query, enabling dynamic filtering in your frontend.

Visual Search API​

To perform a visual search using an image, send a POST request to:

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

Request Payload​

{
    "img": str,
    "session_id": str,
    "user_id": str
}

Parameter Details​

  • img: The image to search with, provided as a base64-encoded string (e.g., "data:image/jpeg;base64,...").
  • session_id: Unique identifier for the user session.
  • user_id: Unique identifier for the user.

This endpoint analyzes the provided image and returns detected objects and their embeddings, which can be used for further recommendations.

Response Example:​

{
    "detections": [
        {
            "xcenter": 810,
            "ycenter": 1086,
            "width": 1211,
            "height": 743,
            "confidence": 0.9591711759567261,
            "class": 24,
            "name": "",
            "embedding": [...]
        }
    ]
}

Response Breakdown​

The response returns an array of detected objects, each with the following properties:

  • 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: Confidence score for the detection (value between 0 and 1).
  • class: Numeric class ID representing the detected object type.
  • name: Name of the detected object class (may be empty if not available).
  • embedding: Numerical vector representing the object's features, useful for similarity comparisons or further recommendations.

This structure allows you to identify and process objects detected within the submitted image.

Visual Recommend API​

Recommendation Request​

To get product recommendations based on a visual embedding, send a POST request to:

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

Request Payload​

{
    "img": [float],
    "detected_class": int,
    "n_rec": int,
    "session_id": str,
    "user_id": str
}

Parameter Details​

  • img: The embedding vector obtained from the Visual Search API response.
  • detected_class: The class ID of the detected object from the Visual Search API.
  • n_rec: Number of recommendations to return.
  • session_id: Unique identifier for the user session.
  • user_id: Unique identifier for the user.

This endpoint returns visually similar product recommendations based on the provided embedding and detected object class.

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 returns an array of recommended products. Each product object contains the following fields:

  • id: Internal identifier for the item.
  • item_id: External product identifier.
  • name: Name of the product.
  • brand_id: Unique identifier for the brand.
  • brand_name: Name of the brand.
  • page_ids: Array of page IDs where the product appears.
  • page_names: Names of the associated pages.
  • category_id: Identifier for the product category.
  • category_name: Name of the product category.
  • gender: Intended gender for the product (if applicable).
  • price: Current price of the product.
  • market_price: Original price before any discounts.
  • discount: Discount percentage applied to the product.
  • url: Direct URL to the product page.
  • images: Array of image URLs for the product.
  • tags: List of additional tags or attributes associated with the product.

This structure provides all the necessary details to display visually recommended products in your frontend.

Merge Users API​

When to Use​

If the user_id changes for a user (for example, after a login or account merge), you must notify the system by sending a POST request to:

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

Request Payload​

{
    "old_user_id": str,
    "new_user_id": str
}

Parameter Details​

  • old_user_id: The previous user identifier (before the change).
  • new_user_id: The new user identifier (after the change).

This ensures that all activity and recommendations are correctly associated with the updated user profile.

Response Example​

{
    "status": "ok"
}