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.