Skip to content

Latest commit

 

History

History
173 lines (125 loc) · 8.23 KB

README.md

File metadata and controls

173 lines (125 loc) · 8.23 KB
Raw

CompaniesHouse::Client

GH Actions

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.

To interact the older CompaniesHouse XML-based API, see the gem companies-house-gateway. (Monthly subscription fees, and other fees, may apply.)

Quick start:

export COMPANIES_HOUSE_API_KEY=YOUR_API_KEY_HERE
  • Install companies-house-rest through RubyGems
  • Create and use a client:
require 'companies_house/client'
client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY'])
profile = client.company('07495895')

Overview

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 NI or SC.

Authentication

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

Client Initialization

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:

Key Description
:api_key Required. The API key received after registration.
:endpoint Optional. Specifies the base URI for the API (e.g. if using a self-hosted version)
:instrumentation Optional. Instruments the request/response (see Instrumentation for details)

Instrumentation

By default, no instrumentation is being applied. If you are using Rails or the ActiveSupport gem, instrumentation will happen automatically via ActiveSupport::Notifications

Requests

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:

Client Method Endpoint Description
.company(company_number) GET /company/:company_number Retrieves a company profile.
.officers(company_number) GET /company/:company_number/officers Retrieves a list of company officers.
.company_search(query, items_per_page: nil, start_index: nil) GET /search/companies Retrieves a list of companies that match the given query.

.company

This method implements the readCompanyProfile API and returns the full companyProfile resource.

.officers

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 items key from the officerList resource(s) which it reads.

.company_search

This method implements the searchCompanies API and returns the list of companySearch resources that match the given query. The items_per_page and start_index parameters are optional.

.filing_history_list

This method implements the filingHistoryList API and returns the full filingHistoryList resource.

.filing_history_item

This method implements the filingHistoryItem API and returns the full filingHistoryItem resource.

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.

Error Handling

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:

Field Description
response The Net::HTTP response object from the failed API call.
status A string containing the response status code.

Certain API responses will raise an instance of a more specific subclass of CompaniesHouse::APIError:

Status Error Description
401 CompaniesHouse::AuthenticationError Authentication error (invalid API key)
404 CompaniesHouse::NotFoundError Not Found. (No record of the company is available.)
429 CompaniesHouse::RateLimitError Application is being rate limited

The client will not catch any other errors which may occur, such as errors involving network connections (e.g. Errno::ECONNRESET).

Development

This gem is configured for development using a bundler workflow. Tests are written using RSpec, and Rubocop is used to provide linting. Bug reports and pull requests are welcome on this project's GitHub repository.

To get started:

bundle install --path vendor

To run all tests and Rubocop:

bundle exec rake