Skip to content

Advisable.ai

Logo img

Introduction

Advisable.ai is a next-gen, easy to use recommendation engine ready for production

Docs: https://docs.advisable.ai/

Advisable.ai is a modern, fast (high performance), recommender system for customized recommendations based on your e-shop.

The key features are:

  • Speed: Advisable.ai used graphs as its infrastructure, something that plays key role in performance.
  • Customizable: Gives you the ability to ask specific recommendations per customer.
  • Reliable: Handles any number of requests per day for your e-shop.
  • Easy: Easy to get started and intergrate it in your site as well as to ask for recommendations.

Visit docs for more information or keep reading to get started! 🐜

Where to use

E-commerce    Marketplaces

Thanks to the simple integration process, you will be able to provide content, product, or specialized personalization on your website, web app, mobile app, or emailing in a short time.

Getting started

The first thing you need is your database at Advisable.ai and the corresponding secret key.

We provide an easy to use API that will get you started quickly and you don’t need to use any languages, you can use directly the REST API (see below for details about authentication).

Authentication

Assuming you created a client as described above you are gonna need to login in the /v1/auth/token endpoint with the credentials you entered and get the access token which you need to send as Authentication header, in order to create a new app and get the app_id and app_secret that will be used for further authentication for any next request. So upon creating a new client and a new app you can start replicating your shop throught the app instance.

We use app_id and app_secret for authorization of any action so make sure to keep them secure and safe.

We are gonna need a catalog in order to store/refresh your items (products) in the shop. We request a valid url for that which must stay online at any time and provide your items in XML format. Every app can only have one catalog.

Finally we need to store user ids under the same app in order to correlate it with item interactions and provide personalized recommendations for each one of your customers (users).

How to integrate

High level the integration flow is easy to understand and pretty simple to implement. Upon collecting all the interactions the user creates you have to send docs advisable to process them and give recommendations for each one of your users.

The recommendations are usually shown to a user at a website, in a mobile app or within an email campaign.

Apps

In order to use Advisable.ai's API you first need to create an app. App is the entity that tries to encapsulate shops. You will be provided with an id and a secret and that should be included in every follow up request for the next endpoints in the form of headers as a form of authorization.

Catalogs

Catalog is the entity that holds all of your shop's items catalog and it's related only with your app, hence you need the credentials mentioned above in order to make successful requests.

Creating a catalog

Now that you created your app you need a way to provide Advisable.ai with the items of your shop, that's done through /v1/catalogs endpoint. We will need a name and a target URL which proovides us with the XML of your shop so we can parse all the items from there. Please make sure your XML is valid in the /v1/xml/validate endpoint before submitting for a new catalog.

Users

Users entity is the entity that holds all the users of your shop and it is also related to your app. You need to register your users to Advisable.ai so it starts to learn their preferences and recommend them new products from your e-shop.

Creating a user

In order to register your users you will be asked to provide a name and and an external_id which is meant to be the same as the user's id so you can ask recommendation later on for that specific user. Registering users is done through /v1/users/ endpoint.

Updating a user

Updating users is done by sending a put request in /v1/users/ endpoint. One thing to be noted here is that if you include external_id in payload (the id of the user in your database) it will automatically trigger an update in all tables and updating all the interactions refering that specific user.

Interactions

Basic properties

They all have similar properties, let's have a look at them:

  • timestamp: Optional[str] - the time of an interaction timed in miliseconds, could be a number or a string (with a valid ms number). This will play an important role in identifying frequently bought together items so ideally you should provided it as much as possible.
  • recommendation_id: Optional[str] - the id that was returned to you along with the recommendation data. It is highly recommended that you save that id and send it along with the interaction if that's the case (will be used for providing you with metrics as well later on)
  • user_id: str - The user id that corresponds the id of the user in your database
  • item_id: str - The item id that corresponds the id of the item in your database
  • value: float - This property only exists in ratings payload. Should be any positive float number between 0 and 5.

Optional properties

These are all optional and are used only in some interactions as you can find in docs:

  • price: - the price of an item the user purchased it for
  • amount: - The amount of pieces if a user purchases more than one of the same product
  • duration: - The amount of time a user stared at a product (in ms)

Send interactions

Interactions are the most valuable information for the algorithms in the recommender engine.

The types of interactions are listed bellow:

  • bookmark: it will be sent to the system every time a user bookmarks an item

  • rating: it will be sent to the system every time a user rates an item

  • purchase: it will be sent every time a user completes the main desired goal (a conversion).

  • cart addition: - it will be sent to the system every time a user adds an item into their cart

  • view: it will be sent to the system every time a user views a detail of an item

The endpoints are consistent in the form of:

  • [POST] /v1/{interaction_type} to create an interaction
  • [GET] /v1/users/{user_id}/{interaction_type} to list all the interactions of this type of a specific user
  • [GET] /v1/items/{item_id}/{interaction_type} to list all the interactions of this type with a specific item

  • [DELETE] /v1/{interaction_type} to delete all the interactions. This endpoint is dynamic so you can determine the velocity of the delete. It accepts item_id, user_id, and timestamp. Eg: if you only pass an item_id this call will delete all the interactions containing this specific item. If you pass a user_id as well it will delete the interactions between this user and this item, and if you pass a timestamp the interactions that match all of the three criteria will be deleted.

  • [POST] /v1/purchases/batch This endpoint allows to create batch purchases, it is only available for the purchases for the moment. It works similarly as the normal create but it accepts an array as an input. You can find more info here.

Transfer user interactions

We provide an endpoint for transfering interactions from one user to another. One common use case might be if you have recorded the activity of a guest user and later on the same user registers into your e-shop. You can use the /v1/users/{from_user_id}/interactions/transfer/{to_user_id} or /v1/users/{user_id} including the new external_id to transfer all the interactions. The first endpoint provides a delete_user flag (defaults to True) to remove the "old" user, considering he is a guest.

Items

Item schema

An item can have the properties as listed bellow:

  • item_id str: the id of the item in your database
  • title str: the title of the item
  • description str: the description of the item
  • category str: the category of the item
  • link str: the link of the item in your e-shop
  • image_link str: the link of some image of the item
  • price float: the price of the item
  • vat_rate float: the vat rate this item has on your e-shop (Optional)
  • availability str: a short string with when is this item available (Optional)
  • in_stock boolean: is the item in stock?
  • manufacturer str: the manufacturer of the item (Optional)
  • isbn str: the isbn (The International Standard Book Number) of the item if available (Optional)
  • barcode str: the barcode of the item (Optional)
  • weight str: the weight of the item (Optional)
  • color str: the color of the item (Optional)
  • shipping_cost float: the shipping cost of the item in your e-shop (Optional)
  • quantity int: the quantity of the item in your e-shop (Optional)

The required properties are the ones who doesn't have "(Optional)" on the right. See a full xml example bellow.

XML Sample

Here you can find how your XML should be formed when the Advisable.ai's scraper tries to parse it and add the items on our database.

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <created_at>2022-10-06 08:55:17.099386</created_at>
  <CATALOG>
    <ITEMS>
      <item_id>1</item_id>
      <title>Frezyderm Nazal Cleaner 6</title>
      <description>NaCl saline solution, compatible with homeopathy.</description>
      <category>Acetaminophen (Paracetamol)</category>
      <link>http://myshop.com/items/465332</link>
      <image_link>http://myshop.com/items/465332/images/1</image_link>
      <price>4.34</price>
      <vat_rate>24</vat_rate>
      <availability>in a week</availability>
      <in_stock>true</in_stock>
      <manufacturer>Fujitsu</manufacturer>
      <isbn>54-534-6-347-23</isbn>
      <barcode>567634287234</barcode>
      <weight>11</weight>
      <color/>
      <shipping_cost>2.3</shipping_cost>
      <quantity>6</quantity>
    </ITEMS>
    <ITEMS>
      <item_id>2</item_id>
      <title>Calm Life 2</title>
      <description>It has analgesic, antipyretic and weak anti-inflammatory action.</description>
      <category>Acetaminophen (Paracetamol)</category>
      <link>http://myshop.com/items/465332</link>
      <image_link>http://myshop.com/items/465332/images/1</image_link>
      <price>9.12</price>
      <vat_rate>24</vat_rate>
      <availability>in a week</availability>
      <in_stock>true</in_stock>
      <manufacturer>Xiaomi</manufacturer>
      <isbn>54-534-6-347-23</isbn>
      <barcode>543799678957689</barcode>
      <weight>12.0</weight>
      <color/>
      <shipping_cost>12.0</shipping_cost>
      <quantity>2</quantity>
    </ITEMS>
  </CATALOG>
</root>

XML Validator

If you are not sure whether your XML is valid you can check it here. Also even if you are sure please use the validator. You will receive instructional errors in case your XML is not in the expected form.

Recommendations

Getting recommendations!

It is very easy to get recommendations as you will see bellow:

  • Recommend items to user: The system recommends items to a given user depending on his/her personal taste. This case can be used for example at your homepage. It comes with a few algorithms for you to pick and an auto flag if you can't pick.

  • Recommend items to item: The system recommends items that are somehow related to a given item. The system can take into account also a target user, so this case is useful for example in a detail page of a product or article because the endpoint will give the user a list of related items that he/she might be also interested in.

  • Recommend users to item: The system recommends users that are likely to be interested in a specific item depending on the user's personal taste.

  • Frequently bought together: The system recommends items that were bought together with the requested item. You can use this endpoint to create frequently bought together sections. There this (/v1/recommendations/fbt/items/?ids=1&ids=2... etc) endpoint for multiple fbt items at once call.

  • Categories: The system recommends categories based on where the user has been more active in terms of categories.

  • Most popular items: The system recommends items that were bought frequently in your e-shop. Not suggested for old users as it doesn't offer any personalization.

Besides the recommended items, a unique ID is returned. If the user interacts (views, purchases, etc.) with a recommended item, you shall set this ID to the recommendation_id parameter of that interaction. This will let Advisable.ai know that an recommendation was succesful and also provide you with some metrics later on. This id will also come handy if you wanna ask for more items/user of the same recommendation. In other words recommendations are generated once and the you can access them with that id whenever you want. By default Advisable.ai will return 4 items/users but you can ask for more with the id of the recommendation as described below.

  • Next items/users: This endpoint allows you to ask more items/user from a specific recommendation if you are the id holder. Think of it like a pagination of a recommendation you generated. Also gives you the ability to limit and skip items as you please. For more info check out here.

  • Recommendations count: This endpoint allows you to get a count of all the recommendations that have been generated in a certain period of time when a filter is given otherwise the total count of recommendations of the app is returned. The filters that are in your disposal are

  • _from - _to: provide dates in UNIX timestamp format eg: 1675866414092 OR

  • last_x_days: provide an integer that will reprsesent the number of last days you want to retrieve the count of recommendations for.

The endpoints

The recommendations endpoints follow a similar pattern with the ones we already saw. Let's take a quick look:

  • [GET] /v1/recommendations/users/{user_id}/items
  • [GET] /v1/recommendations/items/{item_id}/items
  • [GET] -/v1/recommendations/items/{item_id}/users
  • [GET] -/v1/recommendations/fbt/items/{item_id}/users
  • [GET] -/v1/recommendations/fbt/items/
  • [GET] -/v1/recommendations/users/{user_id}/categories
  • [GET] -/v1/recommendations/items/most_popular
  • [GET] -/v1/recommendations/{id}/next
  • [GET] -/v1/recommendations/{id}/count

These were the endpoints that are responsible for providing you with recommendations for your users or your items. We use a few algoriths in Advisable.ai, most of them can be found and ran in /v1/recommendations/users/{user_id}/items and the fbt in url path which we plan to remove at some point so keep that in mind.

Algorithms

  • auto: This is the default value if you can't decide what algorithm you should pick. Let the system do it for you but keep in mind this comes with a little bit slower responses on your request
  • cbf: Content based filtering, use it to suggest products from similar categories for the requested user
  • cf: Collaborative filtering, use it to suggest products from similar users to the requested user
  • fbt: Frequently bought together algorithm, use it for Frequently bought together sections
  • mp: Most popular algorithm, use it when there are not enough data for a given user (new users). Lower success rate on old users, could be used in general sections of an e-shop
  • vbf: This is the views based algorithm. It works similarly with the collaborative filtering but it only considers view events instead. Will work fine for new users upon sending at least a few view events.
  • categories: This endpoint will recommend the most suitable categories upon given a user id.

Other parameters

  • with_descriptions (boolean): Defaults to False, use it to add or remove item descriptions from the payloads.
  • limit (int): Defaults to 4, use it to instruct the API on how many results should be returned in that request. Note that if the limit is high enough but the items returned are less then you probably the algorithm have no more items to show.