ChJsonApi
Companies House JSON API Gem

Ruby Gem to help make requests to Companies House public API.

Version 0.3.2

• Adding support for multiple keys.

Version 0.3.1

• Changing exception thrown on Too Many Requests

Version 0.3.0

• Handling "Too Many Requests" message (CH says that happens when 600 requests are sent in 5 minutes. Then the next requests have the HTTP status header of 429 Too Many Requests)

Companies House JSON API is still in beta, which means that it might eventually change. Until a stable version is launched, this gem is considered on "version 0."

Add this line to your application's Gemfile:

gem 'chjsonapi'

And then execute:

$ bundle

Or install it yourself as:

$ gem install chjsonapi

###Require

Add this line to files where the Gem will be used.

require 'chjsonapi'

###Companies House API Key

To use Companies House API, you need to configure an API Key, which you can obtain from their website.

Before making any requests, you need to initialise the Gem by calling

ChJsonApi.init "YOUR_API_KEY"

Or, if you have more than one key available, you can initialise the Gem with an array of keys by calling

ChJsonApi.init ["FIRST_KEY", "SECOND_KEY", ... , "LAST_KEY"]

###Querying for Company profile

json = ChJsonApi::Company.profile company_number:'COMPANY_NUMBER'
puts json['company_number']

###Querying for Company Registered Office Address

json = ChJsonApi::Company.registered_office company_number:'COMPANY_NUMBER'
puts json['locality']

###Querying for Company Officers List

json = ChJsonApi::Company.officers company_number:'COMPANY_NUMBER'
puts json['items'][0]['address']['premises']

Or any of the optional parameters

json = ChJsonApi::Company.officers company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,order_by:'ORDER_BY'
puts json['items'][0]['address']['premises']

###Querying for a specific Filing History Item

json = ChJsonApi::Company.filing_item company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,order_by:'ORDER_BY'
puts json['transaction_id']

###Querying for Filing History

json = ChJsonApi::Company.filing_list company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,order_by:'ORDER_BY'
puts json['transaction_id']

Or any of the optional parameters

json = ChJsonApi::Company.officers company_number:'COMPANY_NUMBER',items_per_page:X,start_index:X,category:'ORDER_BY'
puts json['transaction_id']

After checking out the repo, run bin/setup to install dependencies. Then, run rake rspec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

The gem is available as open source under the terms of the MIT License.