Introduction

The Lateral API

Tools

Lateral Intelligence Platform API Reference - v1

Warning: This API is no longer online, this documentation only serves as a reference. Please use v5.

API Base URL

https://recommender-api.lateral.io/

Authentication

Every request must be authenticated with your subscription key. This must be as a URL parameter like so:

https://recommender-api.lateral.io/recommend/?subscription-key={YOUR_KEY_HERE}

Requests

All requests will return a JSON object with the header:

Content-Type: application/json

404 Errors

When a request to a path not in the API is made, you will get the following error message:

{
  "statusCode": 404,
  "message": "Resource not found"
}

API Specification

  • Go
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • Shell

Resource Group

Add document/add/

POST/add/Add document
Code Sample

Add a document to your documents collection. Optionally, allows you to store some JSON meta data which is returned when retreiving a document with /fetch.

Parameters
Name Example Description
document_id(string, required) A unique identifier for the document
text(string, required) The contents of the document
meta(string, optional) A JSON encoded string
Response200
Response (200)
{
  "text": "lorem ipsum dolor [...]",
  "created_at": "2014-11-19 23:15:44.545462",
  "meta": "{\\"date\\": \\"2014-11-18\\", \\"type\\": \\"news\\"}",
  "document_id": "my_doc_id"
}
Response406

Returned if the contents of the text parameter does not have enough meaningful words in it.

Response (406)
<html>
    <title>406: less than 25 words recognized</title>
    <body>406: less than 25 words recognized</body>
</html>
Response409

Returned if the document_id has already been used.

Response (409)
<html>
    <title>409: id already exists! document_id doc_id</title>
    <body>409: id already exists! document_id doc_id</body>
</html>

Delete document/delete/

POST/delete/Delete document
Code Sample

Delete a document from your documents collection.

Parameters
Name Example Description
document_id(string, required) The identifier for the document
Response200

The record that was just deleted, meta data included.

Response (200)
{
  "text": "lorem ipsum dolor [...]",
  "created_at": "2014-11-19 23:15:44.545462",
  "meta": "{\\"date\\": \\"2014-11-18\\", \\"type\\": \\"news\\"}",
  "document_id": "my_doc_id"
}
Response404

Returned if the document to be deleted was not found.

Response (404)
<html>
    <title>404: Not Found</title>
    <body>404: Not Found</body>
</html>

Delete all documents/delete-all/

POST/delete-all/Delete all documents
Code Sample

Deletes all documents in your documents collection. Use with caution!

Response200

Returned after all documents have been deleted.

Get a documents/fetch/

GET/fetch/Get a documents
Code Sample

Get a single document.

Parameters
Name Example Description
document_id(string, required) The identifier for the document
Response200
Response (200)
{
  "text": "lorem ipsum dolor [...]",
  "created_at": "2014-11-19 23:15:44.545462",
  "meta": "{\\"date\\": \\"2014-11-18\\", \\"type\\": \\"news\\"}",
  "document_id": "my_doc_id"
}
Response404

Returned if the document with the specified document_id was not found.

Response (404)
<html>
    <title>404: Not Found</title>
    <body>404: Not Found</body>
</html>

List all documents/list/

GET/list/List all documents
Code Sample

Returns a list of all document ids

Response200
Response (200)
[
  "doc_id_1",
  "doc_id_3",
  "doc_id_5"
]

Recommend by ID/recommend-by-id/

POST/recommend-by-id/Recommend by ID
Code Sample

Returns a list of documents that are similar to the document with the given document_id.

Parameters
Name Example Description
document_id(string, required) The identifier for the document to get recommendations for
results(integer, optional) How many results to return - Default = 20, Max. = 200
select_from (optional, string) ... A JSON-encoded list of `document_id`s(strings, required)
Response200

The recommendations, an array of objects containing a distance and a document_id. These are sorted by the distance to the specified document.

Response (200)
[
  {
    "distance": 0.000248,
    "document_id": "doc_id_2"
  },
  {
    "distance": 0.000419,
    "document_id": "doc_id_1"
  }
]
Response404

Returned if the document with the specified document_id was not found.

Response (404)
<html>
    <title>404: Not Found</title>
    <body>404: Not Found</body>
</html>

Recommend by text/recommend-by-text/

POST/recommend-by-text/Recommend by text
Code Sample

Returns a list of documents that are similar to the given text.

Parameters
Name Example Description
text(string, required) The text to get recommendations for
results(integer, optional) How many results to return - Default = 20, Max. = 200
select_from (optional, string) ... A JSON-encoded list of `document_id`'s(strings, required)
Response200

The recommendations, an array of objects containing a distance and a document_id. These are sorted by the distance to the specified document.

Response (200)
[
  {
    "distance": 0.000248,
    "document_id": "doc_id_2"
  },
  {
    "distance": 0.000419,
    "document_id": "doc_id_1"
  }
]
Response406

Returned if the contents of the text parameter does not have enough meaningful words in it.

Response (406)
<html>
    <title>406: less than 25 words recognized</title>
    <body>406: less than 25 words recognized</body>
</html>

Update a documents meta/update-meta/

POST/update-meta/Update a documents meta
Code Sample

Update the meta field of the record with the given document_id.

Parameters
Name Example Description
document_id(string, required) A unique identifier for the document
meta(string, required) A JSON encoded string
Response200
Response (200)
{
  "text": "lorem ipsum dolor [...]",
  "created_at": "2014-11-19 23:15:44.545462",
  "meta": "{\\"date\\": \\"2014-11-18\\", \\"type\\": \\"news\\"}",
  "document_id": "my_doc_id"
}
Response404

Returned if the document to be updated was not found.

Response (404)
<html>
    <title>404: Not Found</title>
    <body>404: Not Found</body>
</html>

Update a documents text/update-text/

POST/update-text/Update a documents text
Code Sample

Update the meta field of the record with the given document_id.

Parameters
Name Example Description
document_id(string, required) A unique identifier for the document
text(string, required) The contents of the document
Response200
Response (200)
{
  "text": "lorem ipsum dolor [...]",
  "created_at": "2014-11-19 23:15:44.545462",
  "meta": "{\\"date\\": \\"2014-11-18\\", \\"type\\": \\"news\\"}",
  "document_id": "my_doc_id"
}
Response404

Returned if the document to be updated was not found.

Response (404)
<html>
    <title>404: Not Found</title>
    <body>404: Not Found</body>
</html>
Response406

Returned if the contents of the text parameter does not have enough meaningful words in it.

Response (406)
<html>
    <title>406: less than 25 words recognized</title>
    <body>406: less than 25 words recognized</body>
</html>