Build Status Gem Version Yard Docs

This is a Ruby wrapper around the Lateral Conceptual text-matching API. At the moment it only supports /add, /recommend-by-text, /recommend-by-id and our pre-populated recommenders. You can find the full API reference here.


Add this line to your application's Gemfile:

gem 'lateral_recommender'

And then execute:

$ bundle install


Get an API key

An API key is required in order to use our API. To do this go to our docs page and click the 'Get Access' button in the top right. Choose the 'Conceptual text-matcher' API and you'll get emailed details of how to get your key.

Use the API

Initialize LateralRecommender with your API key by running:


Add a document

To add a document to the API call:

api.add document_id: 'document_id', text: 'document text'

Please be aware that if you don't send enough meaningful text the API will return an error. So please ensure there is at least 100 or so words in the document you're adding.

Recommend by text

To get recommendations for some text, use recommend_by_text:

api.recommend_by_text 'document text'

Recommend by ID

To get recommendations for a document that's in the API, use recommend_by_id:

api.recommend_by_id 'document_id'

This returns an array of Hashes containing a document_id and distance.

Pre-populated recommenders

If you don't want to insert your own documents to the API, you can query one of our pre-populated recommenders:

  • arXiv - 1M+ academic papers in Physics, Mathematics and Computer Science (updated daily)
  • News - 250,000+ curated news articles (updated every 15mins)
  • PubMed - 20M+ medical journals (from June 2014)
  • SEC Data - 6,000+ yearly financial reports / 10-K filings (from 2014)
  • Wikipedia - 463,000 Wikipedia pages (which had 20+ page views in 2013)

To use one of these, initialize LateralRecommender with a second argument containing the corpus:

api = YOUR_API_KEY, 'news'

The available values are arxiv, news, pubmed, sec or wikipedia. These allow you to query the recommender using recommend_by_text or recommend_by_id without the need for adding your own documents. By text:

api.recommend_by_text 'document text'

Or with a document ID:

api.recommend_by_id 'arxiv-'

Note: For the SEC data, you need to set a collections array:

api.recommend_by_text 'document text', collections: '["item1a"]'

Read the Pre-populated-recommenders documentation for more.


  1. Fork it ( )
  2. Create spec/env_vars.rb file containing ENV['API_KEY'] = 'YOUR_KEY'
  3. Create your feature branch (git checkout -b my-new-feature)
  4. Commit your changes (git commit -am 'Add some feature')
  5. Push to the branch (git push origin my-new-feature)
  6. Create a new Pull Request


To test the gem, run bundle exec rspec. Note: your API key must be un-used.