Azure Recommendations API

Home » Azure Recommendations API

The Recommendations API built with Microsoft Azure Machine Learning helps your customer discover items in your catalog. Customer activity in your digital store is used to recommend items and to improve conversion in your digital store.The recommendation engine may be trained by uploading data about past customer activity or by collecting data directly from your digital store. When the customer returns to your store you are able to feature recommended items from your catalog that may increase your conversion rate.

Common Scenarios Supported By Recommendations

Frequently Bought Together (FBT) Recommendations

In this scenario, the recommendations engine recommends items that are likely to be purchased together in the same transaction with a particular item.

For instance, in the following example, customers who bought the Wedge Touch Mouse were also likely to buy at least one of the following products in the same transaction: Wedge Mobile Keyboard, the Surface VGA Adapter and Surface 2.

Item to Item Recommendations

A common scenario that uses this capability, is “people who visited/clicked on this item, also visited/clicked on this item.”

For instance, in the following example, most people who visited the “Wedge Touch Mouse” details page also visited the pages related to other mouse devices.

Customer to Item Recommendations

Given a customer’s prior activity, it is possible to recommend items that the customer may be interested in.

For instance, given all movies watched by a customer, it is possible to recommend additional content that may be of interest to the customer.

General overview

This document is a step-by-step guide. Our objective is to walk you through the steps necessary to train a model and to point you to resources that will allow you to consume the model from your production environment.

This exercise will take about 30 minutes.

To use Recommendations API, you need to take the following steps:

  1. Create a model – A model is a container of your usage data, catalog data and the recommendation model.
  2. Import catalog data – A catalog contains metadata information about the items.
  3. Import usage data – Usage data can be uploaded in one of 2 ways (or both):
    • By uploading a file that contains the usage data.
    • Sending data acquisition events. Usually you upload a usage file in order to be able to create an initial recommendation model (bootstrap) and use it until the system gathers enough data by using the data acquisition format.
  4. Build a recommendation model – This is an asynchronous operation in which the recommendation system takes all the usage data and creates a recommendation model. This operation can take several minutes or several hours depending on the size of the data and the build configuration parameters. When triggering the build, you will get a build ID. Use it to check when the build process has ended before starting to consume recommendations.
  5. Consume recommendations – Get recommendations for a specific item or list of items.

Let’s get started!

You will start building a Recommendations model. Then we’ll guide you on how to use the results generated by the model to power recommendations on an e-commerce site.

Task 1 – Signing up for the Recommendations API

In this task, you’ll sign up for the Recommendations API service, and create a recommendations model.

  1. Go to the Azure Portal at and sign in with your Azure account.
  2. Click on + New.
  3. Select the Intelligence option.
  4. Select the Cognitive Services APIs product. This product will allow you to start a subscription for any of the cognitive services APIs (Face, Text Analytics, Computer Vision, etc.). Today we will focus on the Recommendations API.
  5. On the Cognitive Services API landing page, enter the Account name for your Recommendations subscription. (For instace: “MyRecommendations”). This name should not have any spaces in it.
  6. On API type, select Recommendations.
  7. On Pricing tier, you can select a plan. You may select the Free tier for 10,000 transactions/month. This is a free plan, so it is a good way to start trying the system. Once you go to production, we recommend you consider your request volume and change the plan type accordingly. (Note: You can have only one Free tier subscription at a time)
  8. Select a Resource Group, or create a new one if you don’t have one already.
  9. You may change other elements in the Create dialog. We should point out that the resource provider today is only supported from United States data centers.
  10. Once you are done with any selections, click Create.
  11. Wait a few minutes for the resource to be deployed. Once it is deployed, you can go to the Keys section in the Settings blade where you will be provided a primary and secondary key to use the API. Copy the primary key, as you’ll need it when creating your first model.

Task 2 – Did you bring your data?

The Recommendations API will learn from your catalog and your transactions in order to provide good product recommendations. That means you need to feed it with good data about your products (We call this a catalog file) and a set of transactions large enough for it to find interesting patterns of consumption (We call this usage).

  1. Usually, you would query your transactions database for these pieces of information. Just in case you don’t have them handy, we have provided some sample data for you based on Microsoft Store transaction data.You can download the data from here. Copy and unpack the MsStoreData.Zip into a folder on your local machine.


    The sample code that you will download and run in Task 3 has sample data already embedded inside it — so this task is optional. That said, this Task will allow you to download more realistic data sets and allow you to understand the inputs into the Recommendations API better.

  2. Now let’s take a look at the catalog file. Navigate to the location where you copied the data. Open the catalog file in notepad.You will notice that the catalog file is pretty simple. It has the following format <itemid>,<item name>,<product category>

    AAA-04294,OfficeLangPack 2013 32/64 E34 Online DwnLd,Office
    AAA-04303,OfficeLangPack 2013 32/64 ET Online DwnLd,Office
    C9F-00168,KRUSELL Kiruna Flip Cover for Nokia Lumia 635 – Camel,Accessories

    We should point out that a catalog file can be much richer, for instance, you can add metadata about the products (We call these item features). You should see the catalog format section in the API Reference for more details on the catalog format.

  3. Let’s do the same with the usage data. You will notice that the usage date is of the format <User Id>,<Item Id>,<Time Stamp>,<Event>.

    00037FFEA61FCA16,288186200,2015/08/04T11:02:52,Purchase 0003BFFDD4C2148C,297833400,2015/08/04T11:02:50,Purchase 0003BFFDD4C2118D,297833300,2015/08/04T11:02:40,Purchase 00030000D16C4237,297833300,2015/08/04T11:02:37,Purchase 0003BFFDD4C20B63,297833400,2015/08/04T11:02:12,Purchase 00037FFEC8567FB8,297833400,2015/08/04T11:02:04,Purchase

Notice that the first three elements are mandatory. The event type is optional. You can check out the usage format for more information on this topic.

How much data do you need?

Well, it really depends on the usage data itself. The system learns when users buy different items. For some builds like FBT, it is important to know which items are purchased in the same transactions. (We call this co-occurrences). A good rule of thumb is to have most items be in 20 transactions or more, so if you had 10,000 items in your catalog, we would recommend that you have at least 20 times that number of transactions or about 200,000 transactions. Once again, this is a rule of thumb. You will need to experiment with your data.

Task 3 – Creating a recommendations model

Now that you have an account and you have data, let’s create your first model.

In this task, you will use the sample application to build your first model.

    1. First of all, you should be aware of the Recommendations API Reference.
    2. Download the Sample Application to a local folder.
    3. Open in Visual Studio the RecommendationsSample.sln solution located in the C#folder.
    4. Open the SampleApp.cs file. Note that the following steps in the file:
      • Create a Model
      • Add a catalog file
      • Add a usage file
      • Trigger a build for the Model
      • Get a recommendation based on a pair of items
    5. Replace the value of the AccountKey field with the key from Task 1.
    6. Step through the solution, and you will see how a model gets created.
    7. Try replacing the catalog and usage files you just downloaded to create a new model for the Microsoft Store, or for book recommendations. You will need to change the model name as well, and the items for which you request recommendations.
    8. When the model is created, take note of the model ID as you will need it when requesting recommendations in your production environment.


Learn more about build types and how to evaluate the quality of builds here.

Putting your model into production!

Now that you understand how to create a model and consume recommendations, the next step is to put it in production on your website, mobile application or integrate into your CRM or ERP system. Obviously, each of these implementations would be different. Since the Recommendations API are requested as a web-service, you should be able to call it from any of these different environments easily.


If you want to show recommendations from a public client (for instance, your e-commerce site), you should create a proxy server to provide the recommendations. This is important so that your API Key is not exposed to external (potentially untrusted) entities.

Here are a few ideas of locations where you can use Recommendations:

Product Page

Item Recommendations

If the model was trained on purchase data, it will allow your customer to discover products that are likely to be of interest to people that have purchased the source item.

If the model was trained on click data, it will allow your customer to discover products that are likely to be visited by people that have visited the source item. This type of model may return similar items.

Frequently Bought Together Recommendations

A frequently bought together build could be trained, so you can get sets of items are likely to be purchased together with this item.

Check out Page

Item Recommendations

A recommendations model could take as input a list of items. So you could pass all the items in the basket as input to get recommendations. In this case, the model will provide recommendations that are of interest given all the items in the basket.

Landing Page

User Recommendations

A recommendations model can take as input the user id. This will use the history of transactions by that user to provide personalized recommendations to the user specified.

Check out the Get Item Recommendations Documentation.


Getting Started Guide

Collecting Data to Train your Model

Build Types and Model Quality

API Reference

Source: Recommendations API | Microsoft Docs

By | 2018-03-16T11:54:18+00:00 February 2nd, 2018|Azure Recommendations API, Technologies|