Introduction

The Lateral API

Pre-populated datasets

Tools

Sign-up for an API Key

News Recommender

The news recommender contains 1M+ curated news articles, updated every 15 minutes.

JSON spec

The recommender responds with an array of objects in the following format:

Note: ... has been used to truncate long fields

[
  {
    "document_id": "1807247",
    "similarity": 0.982821,
    "title": "Piano playing transformed into Playstation controllers that play ...",
    "url": "http://www.foobarflies.io/pianette/",
    "published": "2015-02-18T14:30:02.000Z",
    "author": "A Blog",
    "image": "http://www.foobarflies.io/content/images/2015/02/fina.jpg",
    "thumbnail": "https://images.getnewsbot.com/1807247.jpg",
    "summary": "We transformed two classical pianos into Playstation 2 controlers ...",
    "source_name": "Hacker News",
    "source_slug": "hacker-news"
  },
  {
    "document_id": "316776",
    "similarity": 0.942164,
    "title": "For my final project I built a sous-vide immersion cooker (mit.edu)",
    "url": "http://fab.cba.mit.edu/classes/863.14/people/matthew_arbesfeld/2014/12/14/final-project/",
    "published": "2014-12-15T09:20:01.000Z",
    "author": "Matthew Arbesfeld",
    "image": "http://fab.cba.mit.edu/classes/863.14/people/matthew_arbesfeld/img/output_ssr_powered.jpg",
    "thumbnail": "https://images.getnewsbot.com/316776.jpg",
    "summary": "Matthew Arbesfeld's website for MAS.863 -- How to Make Almost Anything",
    "source_name": "Hacker News",
    "source_slug": "hacker-news"
  },
  ...
]

Each field of the document object is described below:

FieldTypeDetails
document_idStringID of the document to be used in /documents/:id/similar
similarityFloatThe similarity to the input document or text (higher is closer)
titleStringTitle of the article
urlURLURL of the article
publishedDateDate the article was published
authorStringAuthor of the article
imageURLThe image from the article
thumbnailURLThumbnail of the image
summaryStringSummary of the article
source_nameStringWhere the article was found
source_slugStringsource_name but in slug form

Usage

Once you have a key, you can get recommendations in the terminal using the following cURL command:

curl --request POST \
  --url https://news-api.lateral.io/documents/similar-to-text \
  --header 'content-type: application/json' \
  --header 'subscription-key: API_KEY' \
  --data '{"text":"Machine learning is a subfield of computer science that evolved from the study of pattern recognition and computational learning theory in artificial intelligence. Machine learning explores the construction and study of algorithms that can learn from and make predictions on data."}'

Let’s say that you have some text and you want to get news articles that are conceptually similar to the text. This is possible with /documents/similar-to-text. The first thing that you will need to do is get an API key.

This will return a JSON object as specified above. If you want to pretty print it for testing (and have Python 2.6+) you can pipe the output of the above command to | python -m json.tool.

Given the ID 1582328 which is the ID for this article we can query the API for similar documents to an ID:

curl --request GET \
  --url https://news-api.lateral.io/documents/1582328/similar/ \
  --header 'content-type: application/json' \
  --header 'subscription-key: API_KEY'

Now you’ve got some results back from the API you might want to get similar documents for one of the results. To do this you can query using /documents/:id/similar.

To call the API in your programming language of choice, check out the API specification where there are code samples available.

Next section: News API Reference