Home » Introduction to Microsofts Recommendation API

Introduction to Microsofts Recommendation API

Today I spent some time to explore the Microsoft Recommendations API. This API is part of the Microsoft Cognitive Services and it allows to show related articles – something like “people who are interested in A are also interested in X,Y and Z”. This can be useful for web shops or blogs but also to see related items/interests.

In this blog post, I’ll:

  • Create the cognitive service and the recommendations API
  • Create and upload some test data
  • Build a model
  • Use that model

Create the recommendations service

The recommendations service is part of the cognitive services and can therefore be found as cognitive service in the Azure portal. Just create it with your preferred pricing tier.

The next step is to visit the recommendations portal which can be found at: https://recommendations-portal.azurewebsites.net/.
The account key is visible in the Azure portal at the recommendations service.

Create a project and some test data

The next step is to create a project in the recommendations portal and add some test data to it. The creation of the project is really simple:

The creation of the test data is the…annoying part. The best is by sure, if you already have some data available that you just have to transform in the right format. If you don’t have any data, then you have to create it. To create a new model, you have to upload 2 files – the catalog csv which contains some articles and a usage csv with some usage data.

catalog csv
<itemid>,<item name>,<product category>

usage csv
<User Id>,<Item Id>,<Time Stamp>,<Event>

I built a simple application (which I’ll probably convert to a web application and post here) that I used to create the test data. My (test) articles are some popular IT topics:

catalog.csv
1,Cloud Computing,Trend
2,Blockchain,Trend
3,4d Printing,Trend
4,Virtual Reality,Trend
5,Augmented Reality,Trend
6,Machine Learning,Trend
7,Big Data,Trend
8,IoT,Trend
9,Robotics,Trend
10,Smart Home,Trend
11,Chat Bots,Trend
12,Serverless Computing,Trend

Then I created some users and clicked a bit at the different topics. The different users have different preferred topics (e.g. if an user had interest in augmented reality, then I also clicked on virtual reality so that I have some useful testdata):

usage.csv
are,1,2017-07-31T15:07:25,Click
are,2,2017-07-31T15:07:27,Click
are,7,2017-07-31T15:07:28,Click
are,8,2017-07-31T15:07:29,Click
are,6,2017-07-31T15:07:30,Click
are,11,2017-07-31T15:07:31,Click
are,12,2017-07-31T15:07:32,Click
are,1,2017-07-31T15:07:34,Click
are,12,2017-07-31T15:07:35,Click
are,11,2017-07-31T15:07:36,Click
are,12,2017-07-31T15:07:36,Click
are,1,2017-07-31T15:07:37,Click
are,6,2017-07-31T15:07:38,Click
jre,2,2017-07-31T15:07:44,Click
jre,9,2017-07-31T15:07:45,Click
jre,10,2017-07-31T15:07:46,Click
jre,9,2017-07-31T15:07:46,Click
jre,2,2017-07-31T15:07:48,Click
csp,3,2017-07-31T15:07:53,Click
csp,2,2017-07-31T15:07:54,Click
csp,7,2017-07-31T15:07:56,Click
csp,9,2017-07-31T15:07:57,Click
csp,8,2017-07-31T15:07:57,Click
csp,7,2017-07-31T15:07:58,Click
csp,8,2017-07-31T15:07:58,Click
csp,9,2017-07-31T15:07:58,Click
csp,10,2017-07-31T15:07:59,Click
csp,9,2017-07-31T15:07:59,Click
csp,2,2017-07-31T15:07:00,Click
csp,3,2017-07-31T15:07:01,Click
csp,10,2017-07-31T15:07:02,Click
csp,9,2017-07-31T15:07:03,Click
csp,8,2017-07-31T15:07:03,Click
csp,7,2017-07-31T15:07:03,Click
csp,8,2017-07-31T15:07:04,Click
csp,7,2017-07-31T15:07:04,Click
csp,9,2017-07-31T15:07:04,Click
csp,10,2017-07-31T15:07:05,Click
csp,7,2017-07-31T15:07:05,Click
sdu,1,2017-07-31T15:07:12,Click
sdu,12,2017-07-31T15:07:12,Click
sdu,1,2017-07-31T15:07:14,Click
sdu,12,2017-07-31T15:07:16,Click
sdu,1,2017-07-31T15:07:17,Click
sdu,6,2017-07-31T15:07:18,Click
sdu,1,2017-07-31T15:07:19,Click
sdu,12,2017-07-31T15:07:20,Click
sdu,6,2017-07-31T15:07:20,Click
dfr,8,2017-07-31T15:07:27,Click
dfr,1,2017-07-31T15:07:29,Click
dfr,8,2017-07-31T15:07:30,Click
dfr,1,2017-07-31T15:07:31,Click
dfr,7,2017-07-31T15:07:33,Click
dfr,8,2017-07-31T15:07:33,Click
dfr,7,2017-07-31T15:07:34,Click
dfr,6,2017-07-31T15:07:34,Click
dfr,1,2017-07-31T15:07:35,Click
dfr,6,2017-07-31T15:07:35,Click
dfr,7,2017-07-31T15:07:36,Click
dfr,8,2017-07-31T15:07:36,Click
hkr,5,2017-07-31T15:07:42,Click
hkr,4,2017-07-31T15:07:43,Click
hkr,5,2017-07-31T15:07:43,Click
hkr,4,2017-07-31T15:07:44,Click
hkr,5,2017-07-31T15:07:44,Click
hkr,4,2017-07-31T15:07:44,Click
hkr,5,2017-07-31T15:07:45,Click
hkr,4,2017-07-31T15:07:45,Click
hkr,5,2017-07-31T15:07:46,Click
hkr,4,2017-07-31T15:07:46,Click
hkr,5,2017-07-31T15:07:47,Click
hkr,3,2017-07-31T15:07:47,Click
hkr,4,2017-07-31T15:07:47,Click
hkr,5,2017-07-31T15:07:48,Click
hkr,4,2017-07-31T15:07:48,Click
hkr,5,2017-07-31T15:07:49,Click
hkr,4,2017-07-31T15:07:49,Click
aja,3,2017-07-31T15:07:56,Click
aja,4,2017-07-31T15:07:56,Click
aja,5,2017-07-31T15:07:57,Click
aja,4,2017-07-31T15:07:57,Click
aja,5,2017-07-31T15:07:58,Click
aja,4,2017-07-31T15:07:58,Click
aja,5,2017-07-31T15:07:59,Click
aja,12,2017-07-31T15:07:02,Click
aja,5,2017-07-31T15:07:03,Click
aja,4,2017-07-31T15:07:03,Click
aja,5,2017-07-31T15:07:04,Click
are,1,2017-07-31T15:07:08,Click

I uploaded these files to the recommendations portal and build my model with the default parameters:

The build type “Recommendations” will give you “item-to-item recommendations”.

Note: If you really want useful results, then you need much more data. In my sample, I have less than 100 clicks. All my articles have the same category and I don’t use other events like “Purchase” or “AddShopCart”. So, I really use very simple data, but it already gives some results (!) which should be enough for this sample.

Testing the model

When the model is ready, you can click the score button to test it. I did so and if I select “Cloud Computing” in the UI, then the most recommended topic is “Machine Learning”. So, it seems that people who are interested in “Cloud Computing” are also interested in “Machine Learning”.

Let’s try something else – “Augmented Reality”:

Get an item-to-item recommendation via C#

The item-to-item recommendation is an API call which is described in detail here:
https://westus.dev.cognitive.microsoft.com/docs/services/Recommendations.V4.0/operations/56f30d77eda5650db055a3d4

I used this API call and (very quickly) build a sample which gets the data. The sample below is by sure not a best practice sample because it does for example not contain any error handling. You can use it as base for your implementation and extend it for your needs:

using System;
using System.Linq;
using System.Net.Http;
using System.Threading.Tasks;

namespace RecommendationsApiSample
{
    static class Program
    {
        public class RecommendationResult
        {
            public Recommendeditem[] RecommendedItems { get; set; }
        }
        public class Recommendeditem
        {
            public Item[] Items { get; set; }
            public float Rating { get; set; }
            public string[] Reasoning { get; set; }
        }
        public class Item
        {
            public string Id { get; set; }
            public string Name { get; set; }
            public string Metadata { get; set; }
        }


        static void Main()
        {
            string key = ""; // TODO: insert one of the keys of the recommendation service
            string modelId = ""; // TODO: insert the id of the model (just click score at your model and you'll see it)
            string articleId = "1";
            int numberOfResults = 3;
            double minimalScore = 0.5;

            var getData = GetRecommendation(key, modelId, articleId, numberOfResults, minimalScore);
            getData.Wait();
            var result = getData.Result;

            foreach(var item in result.RecommendedItems)
            {
                Console.WriteLine(item.Reasoning.First()); 
            }
            
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }

        static async Task<RecommendationResult> GetRecommendation(string key, string modelId, string itemId, int numberOfResults, double minimalScore)
        {
            string minScore = minimalScore.ToString("0.00", System.Globalization.CultureInfo.InvariantCulture);
            string url = $"https://westus.api.cognitive.microsoft.com/recommendations/v4.0/models/{modelId}/recommend/item?itemIds={itemId}&numberOfResults={numberOfResults}&minimalScore={minScore}";

            var client = new HttpClient();
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", key);

            var result = await client.GetAsync(url);
            var resultAsJson = await result.Content.ReadAsStringAsync();

            var rcresult = Newtonsoft.Json.JsonConvert.DeserializeObject<RecommendationResult>(resultAsJson);
            return rcresult;
        }
    }
}

When I enter the correct values in the parameters and I execute it, then the console output looks as follows:

That’s the base to build a greater model with much more data, but the sample above should already show the basics.

Additional information

Quick start guide for the Cognitive Services Recommendations API: https://docs.microsoft.com/en-us/azure/cognitive-services/cognitive-services-recommendations-quick-start
Recommendations API reference: https://westus.dev.cognitive.microsoft.com/docs/services/Recommendations.V4.0

Leave a Reply

Your email address will not be published. Required fields are marked *