Recommendation API documentation

Introduction

The recommendation API allows you to recommend your own documents based on a block of text, based on other documents, or based on a users interests. There are three main data types in the API: Documents, Users and Preferences. It’s possible to insert Documents only and then recommend just from those. Users and Preferences are optional. If you have user data it’s a good idea to insert it to the API from the outset because it will lead to improved recommendations in the future.

The overall flow is to insert your existing documents, users and preferences. Then you will need to update your application so that when documents, users or preferences are added or changed on your side, you send requests to the API to let us know. Once that’s all set up you can call the /documents/{id}/similar, /documents/similar-to-text or /users/{user_id}/recommendations endpoints to get recommendations. They recommend documents based on an existing document, based on a block of text or based on a users preferences respectively.

In order to complete any of the steps below you’ll need an API key. You can obtain one by clicking here and filling out the form. A link to your key will be emailed to you.

What you’ll need to do

Adding documents

To add a document, make a POST request to /documents. The only required field is text which is the body of text that you want to add to the system. There is an optional field meta that can be used to store meta data, e.g. date or url. For demonstration purposes, we’ll just use the text field. You can use the following cURL command to add a document:

curl --request POST \
  --url https://api.lateral.io/documents \
  --header 'content-type: application/json' \
  --header 'subscription-key: YOUR_API_KEY' \
  --data '{"text":"YOUR_TEXT"}'

Replace YOUR_API_KEY with your API key and YOUR_TEXT with the text of the thing that you want to recommend (you could e.g. use our Article Extractor API to get the text of an article from a URL). If the request is succesful, the API responds with a 200 status code and the document object that was created:

{
  "id": 1234,
  "text": "YOUR_TEXT",
  "meta": {},
  "created_at": "2015-03-03T13:49:51.640Z",
  "updated_at": "2015-03-03T13:49:51.640Z"
}

Note: If you don’t put in enough meaningful text inside the value for "text" then you may get recommendations that are not very meaningful back.

You can use the programming language of your choice instead of cURL, of course. There are code samples for several languages available in the API reference. Once you’ve added several documents you can either skip to making recommendations or, if you want to make personalised recommendations to your users, carry on.

In production, save Lateral’s document ID with your own document data. You could do this, for example, by adding a field to your database such as lateral_id that would contain the ID. This will ensure that you can reference the document in our API when recommending by document or when saying a user looked at a document.

Adding users (optional)

A user is a simple representation in our system of a user in your system. Creating a user requires no parameters, it simply creates an ID for the user that you must save for future use. It’s possible to create a user using the following cURL command:

curl --request POST \
  --url https://api.lateral.io/users \
  --header 'content-type: application/json' \
  --header 'subscription-key: YOUR_API_KEY'

A succesful request will return a 200 status code and the user object:

{
  "id": 4321,
  "created_at": "2015-03-03T18:39:01.360Z",
  "updated_at": "2015-03-03T18:39:01.360Z"
}

Please see the API reference for code snippets in other languages. In production, associate this ID with your user data so that when preferences associated to users can be created. For example, you may need to alter your users table to add a lateral_id column. Then, when creating a user in your system, you would send a POST request to /users, get the ID that is returned back and save it along with your other user data.

Adding preferences (optional)

A preference is the association of a User and a Document, indicating that a user has interacted with the document (e.g. read the document). Perferences allow recommendations to be personalised to the user. You can use the following cURL command to create a preference:

curl --request POST \
  --url https://api.lateral.io/users/{user_id}/preferences/{document_id} \
  --header 'content-type: application/json' \
  --header 'subscription-key: YOUR_API_KEY'

Replace {user_id} with the ID of the user and replace {document_id} with the ID of the document that the user has interacted with. For testing purposes you may want to create several preferences for the user you have created. If successful, this will return a 200 status code and an object like this:

{
  "user_id": 4321,
  "document_id": 1234,
  "created_at": "2015-03-04T09:56:36.045Z",
  "updated_at": "2015-03-04T09:56:36.045Z"
}

In production, modify your app so that when a user sees a document, the Lateral API is updated. We strongly recommend that this be an asynchronous call so that there’s no overhead for your users. For example, when a document is seen by a logged in user, get the lateral_id that you’ve associated to the user (e.g. from your database) and the lateral_id that you’ve associated to the document (again, from the database). Now create an asynchronous request (or queued background task) to send a POST to /users/{user_id}/preferences/{document_id}.

Making recommendations

Now that we have added documents, we can make recommendations! If you want to play around with recommendations without having to add documents, you can use one of our pre-populated recommenders such as News or arXiv. A recommendation call will return an array of objects that contain id and similarity. The ID corresponds to the document ID and the similarity is how similar the document is to the input. Similarity is between 1 and 0 with 1 being the most similar to the input. An example of the response is:

[
  {
    "id": 1,
    "similarity": 0.9
  },
  {
    "id": 2,
    "similarity": 0.7
  },
  {
    "id": 3,
    "similarity": 0.5
  }
]

By text

If you have a block of text and want to find similar documents to it then you can use /documents/similar-to-text. You can do this using the following cURL command:

curl --request POST \
  --url https://api.lateral.io/documents/similar-to-text \
  --header 'content-type: application/json' \
  --header 'subscription-key: YOUR_API_KEY' \
  --data '{"text":"YOUR_TEXT"}'

You will need to replace YOUR_API_KEY and YOUR_TEXT.

By document

If you want to recommend documents similar to a document you already have in the API then you can use /documents/{id}/similar. You can do this using the following cURL command:

curl --request GET \
  --url 'https://api.lateral.io/documents/{id}/similar' \
  --header 'content-type: application/json' \
  --header 'subscription-key: YOUR_API_KEY'

You will need to replace YOUR_API_KEY and {id}.

By user

If you want to recommend documents that a user may be interested in then you can use /users/{user_id}/recommendations. You can do this using the following cURL command:

curl --request GET \
  --url 'https://api.lateral.io/users/{user_id}/recommendations' \
  --header 'content-type: application/json' \
  --header 'subscription-key: YOUR_API_KEY'

You will need to replace YOUR_API_KEY and {user_id}.