This Gem implements an API client for the Companies House REST API. It can be used to look up information about companies registered in the United Kingdom. As of July 2016, this API is described by Companies House as a "beta service." More information about this free API can be found on the Companies House API website.
- Register an account via the
Sign In / Registerlink on the CompaniesHouse Developers website
- Register an API key at Your Applications
- Put your API key in an environment variable (not in your code):
- Create and use a client:
require 'companies_house/client' client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY']) profile = client.company('07495895')
This gem is meant to provide a simple synchronous API to look up company profile information and company officers. The data returned is parsed JSON.
This gem provides information on companies by their Companies House company
number. This "company number" is actually a string and should be treated as such.
The string may consist solely of digits (including leading 0s) or begin with
alphabetic characters such as
Using the Companies House REST API requires you to register an account on the CompaniesHouse Developers website and configure an API key. Developers should read the Companies House developer guidelines before using this API, and will note that these guidelines contain several instructions regarding API keys:
- Do not embed API keys in your code
- Do not store API keys in your source tree
- Restrict API key use by IP address and domain
- Regenerate your API keys regularly
- Delete API keys when no longer required
All requests to the API are made through a client object:
require 'companies_house/client' client = CompaniesHouse::Client.new(config)
The client is configured by passing a hash to the constructor. The supported keys for this hash are:
||Required. The API key received after registration.|
||Optional. Specifies the base URI for the API (e.g. if using a self-hosted version)|
||Optional. Instruments the request/response (see Instrumentation for details)|
Once a client has been initialised, requests can be made to the API. Details of the available fields in the response are in the Companies House documentation. The endpoints currently implemented by the gem are:
||Retrieves a company profile.|
||Retrieves a list of company officers.|
||Retrieves a list of companies that match the given query.|
This method implements the officersList
API. It will make one or more requests against this API, as necessary, to obtain
the full list of company officers. It returns only the values under the
key from the
resource(s) which it reads.
Other API Methods
While there are other resources exposed by the Companies House API, this gem does not implement access to these resources at this time.
If a request to the Companies House API encounters an HTTP status other than
200 OK, it will raise an instance of
CompaniesHouse::APIError instead of
returning response data. The error will have the following fields:
||The Net::HTTP response object from the failed API call.|
||A string containing the response status code.|
Certain API responses will raise an instance of a more specific subclass of
||Authentication error (invalid API key)|
||Not Found. (No record of the company is available.)|
||Application is being rate limited|
The client will not catch any other errors which may occur, such as
errors involving network connections (e.g.
This gem is configured for development using a
Tests are written using RSpec, and Rubocop is used to provide linting.
Bug reports and pull requests are welcome on this project's
To get started:
bundle install --path vendor
To run all tests and Rubocop:
bundle exec rake