Introduction

The Lateral API

Pre-populated datasets

Tools

Sign-up for an API Key

Recommendation - Get Started

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. Simply click the Get API Key button to sign-up and we’ll send you a key!

What you’ll need to do

  1. Add documents
  2. Sync future documents (optional)
  3. Integrate user events (optional)
  4. Recommend content!

Adding documents

You can use the following cURL command to add a document:

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

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.

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"
}

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).

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.

Syncing documents

Optional

Edit your app or website so that when content is added or edited, you send us the new document or updated one. This will differ depending on your setup so feel free to live chat with us or send us an email should you need help.

Adding users

Optional

It’s possible to create a user using the following cURL command:

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

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.

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

You can use the following cURL command to create a preference:

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

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.

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"
}

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.

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

An example of the response is:

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

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.

By text

You can do this using the following cURL command:

curl --request POST \
  --url https://api-v6.lateral.io/documents/similar-to-text \
  --header 'content-type: application/json' \
  --header 'subscription-key: YOUR_API_KEY' \
  --data '{"text":"YOUR_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 will need to replace YOUR_API_KEY and YOUR_TEXT.

By document

You can do this using the following cURL command:

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

If you want to recommend documents similar to a document you already have in the API then you can use /documents/{id}/similar.

You will need to replace YOUR_API_KEY and {id}.

Filtering recommendations

The /documents/similar-to-text and /documents/{id}/similar endpoints accept a filter parameter which is a string that can be used to restrict the search to a subset of documents. The filters can be used to restrict the resulting documents by publishing date, tags, or document ids. The query has to be built using a defined query language grammar. Timestamps that are provided as date filter have to comply with the strict RFC3339 format.

The following filters are available:

  • ID filter for a list of document ids:

    id in ['doc_0', 'doc_1', ..., 'doc_N']

  • Tag filter for a single tag id:

    tagged with 'tag_0'

  • Tag filter for a combination of all of a list of tag ids:

    tagged with all of ['tag_0', 'tag_1', ..., 'tag_N']

  • Tag filter for any tag of a list of tag ids:

    tagged with any of ['tag_0', 'tag_1', ..., 'tag_N']

  • Date filter using comparators <, <=, >, >= and a publishing date in strict RFC3339 format:

    published_at < '1999-31-12T00:00:00+01:00'

    or, for specifying UTC time using Z:

    published_at >= '2017-01-01T00:00:00Z'

All of these filters can be combined using the logical operators and and or, where and binds more tightly, negated using not in front of a filter and grouped using round brackets.

An example query that selects only documents that are tagged with 'tag_0' or published after the first of January 2017, but excludes the documents with ids 'doc_0' and 'doc_1', reads as follows:

(tagged with 'tag_0' or published_at > '2017-01-01T00:00:00Z') and not id in ['doc_0', 'doc_1']

By user

You can do this using the following cURL command:

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

If you want to recommend documents that a user may be interested in then you can use /users/{user_id}/recommendations.

You will need to replace YOUR_API_KEY and {user_id}.

Next section: LIP API Reference