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:

Field	Type	Details
`document_id`	String	ID of the document to be used in `/documents/:id/similar`
`similarity`	Float	The similarity to the input document or text (higher is closer)
`title`	String	Title of the article
`url`	URL	URL of the article
`published`	Date	Date the article was published
`author`	String	Author of the article
`image`	URL	The image from the article
`thumbnail`	URL	Thumbnail of the `image`
`summary`	String	Summary of the article
`source_name`	String	Where the article was found
`source_slug`	String	`source_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