Getting Started

Create a namespace / API key

A namespace is a container for all your recommendation data, items and ratings in one namespace do not affect another

To create a new namespace open up the console and click the plus / + icon next to namespaces

This will create a new namespace, with an API key which we will use to send HTTP requests

Namespace's API key

Ingesting data

Data ingestion happens in realtime, each event is a simple JSON payload with three main elements: user_id, item_id, and a score. Both user and item IDs are arbitrary, while score must be a number between 0 and 1

To ingest data we POST a JSON document to the ingestion endpoint: https://api.recomalytics.com/collect

export API_KEY=INSERT YOUR API KEY
curl -X POST https://api.recomalytics.com/collect?apikey=$API_KEY \
    -H "content-type: application/json" \
    -d '{"user_id": "John", "item_id": "Carrots", "score": 0.7}'

Ingested data may take at most 60 seconds to appear in recommendations

Generating Recommendations

Recomalytics has 3 main kinds of recommendations:

• Similar Items: lists the items most similar

• Recommended similar items: lists similar items however the score and order are personalised for the requesting user

• Recommended items: generates a list of items across all items with a score personalised for the requesting user

API Endpoints

For the following examples, these commands were run before hand to populate recommendations:

curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "John", "item_id": "comedy_movie_1", "score": 0.8}'
curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "John", "item_id": "comedy_movie_2", "score": 0.9}'
curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "John", "item_id": "horror_movie_1", "score": 0.2}'

curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "Jack", "item_id": "comedy_movie_1", "score": 0.2}'
curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "Jack", "item_id": "horror_movie_1", "score": 0.8}'
curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "Jack", "item_id": "horror_movie_2", "score": 0.7}'

curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "Jane", "item_id": "horror_movie_1", "score": 0.2}'
curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "Jane", "item_id": "horror_movie_2", "score": 0.1}'
curl -s -X POST https://api.recomalytics.com/collect?apikey=$API_KEY -H "content-type: application/json" -d '{"user_id": "Jane", "item_id": "comedy_movie_1", "score": 0.8}'

Recommendations improve significantly with more data

Similar Items

To request a list of similar items, you need to specify an existing item and call the /similar endpoint:

$ curl "https://api.recomalytics.com/similar?apikey=$API_KEY&item=horror_movie_2"

[
  {
    "item_id": "horror_movie_1",
    "score": 0.9666666666666665
  },
  {
    "item_id": "comedy_movie_1",
    "score": 0.27080128015453203
  }
]

This returns a list of the most similar items, with their item ID and their similarity score

Recommend Similar Items

Similar to above, a list of similar items will be returned however two scores will be provided, a similarity score and a personalised score. Results are ordered by the personalised score. An existing item and a user ID is required, and send to the /recommend endpoint

$ curl "https://api.recomalytics.com/recommend?apikey=$API_KEY&item=horror_movie_2&user=Jack"

[
  {
    "item_id": "comedy_movie_1",
    "similarity_score": 0.27080128015453203,
    "personalised_score": 0.7645161290322582
  },
  {
    "item_id": "horror_movie_1",
    "similarity_score": 0.9666666666666665,
    "personalised_score": 0.5312697215962008
  }
]

Recommend Items

To call this endpoint, send a request to /recommend with only a user ID

$ curl "https://api.recomalytics.com/recommend?apikey=$API_KEY&user=Jane"

[
  {
    "item_id": "comedy_movie_2",
    "score": 0.648262445045573
  },
  {
    "item_id": "horror_movie_1",
    "score": 0.33622238976531893
  },
  {
    "item_id": "horror_movie_2",
    "score": 0.3313009912782784
  }
]