{"id":20290641,"url":"https://github.com/gocardless/companies-house-rest","last_synced_at":"2025-04-11T11:01:58.964Z","repository":{"id":47055750,"uuid":"63257643","full_name":"gocardless/companies-house-rest","owner":"gocardless","description":"Ruby wrapper for the Companies House REST API.","archived":false,"fork":false,"pushed_at":"2024-09-24T14:19:15.000Z","size":185,"stargazers_count":13,"open_issues_count":7,"forks_count":15,"subscribers_count":66,"default_branch":"master","last_synced_at":"2025-04-06T10:03:22.852Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gocardless.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-13T15:25:59.000Z","updated_at":"2024-09-24T14:13:48.000Z","dependencies_parsed_at":"2023-02-19T12:01:10.070Z","dependency_job_id":null,"html_url":"https://github.com/gocardless/companies-house-rest","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fcompanies-house-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fcompanies-house-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fcompanies-house-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gocardless%2Fcompanies-house-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gocardless","download_url":"https://codeload.github.com/gocardless/companies-house-rest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248381716,"owners_count":21094525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T15:08:35.039Z","updated_at":"2025-04-11T11:01:58.930Z","avatar_url":"https://github.com/gocardless.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CompaniesHouse::Client\n\n[![GH Actions](https://github.com/gocardless/companies-house-rest/actions/workflows/main.yml/badge.svg)](https://github.com/gocardless/companies-house-rest/actions)\n\nThis Gem implements an API client for the Companies House REST API. It can be\nused to look up information about companies registered in the United Kingdom.\nAs of July 2016, this API is described by Companies House as a \"beta service.\"\nMore information about this free API can be found\n[on the Companies House API website](https://developer.companieshouse.gov.uk/api/docs/index.html).\n\nTo interact the older [CompaniesHouse XML-based API](http://xmlgw.companieshouse.gov.uk/),\nsee the gem [companies-house-gateway](https://github.com/gocardless/companies-house-gateway-ruby).\n(Monthly subscription [fees](http://xmlgw.companieshouse.gov.uk/CHDpriceList.shtml), and other fees, may apply.)\n\nQuick start:\n\n* Register an account via the `Sign In / Register` link\n[on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)\n* Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications)\n* Put your API key in an environment variable (not in your code):\n\n``` shell\nexport COMPANIES_HOUSE_API_KEY=YOUR_API_KEY_HERE\n```\n\n* Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest)\n* Create and use a client:\n\n``` ruby\nrequire 'companies_house/client'\nclient = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY'])\nprofile = client.company('07495895')\n```\n\n## Overview\n\nThis gem is meant to provide a simple synchronous API to look up company profile\ninformation and company officers. The data returned is parsed JSON.\n\nThis gem provides information on companies by their Companies House company\nnumber. This \"company number\" is actually a string and should be treated as such.\nThe string may consist solely of digits (including leading 0s) or begin with\nalphabetic characters such as `NI` or `SC`.\n\n## Authentication\n\nUsing the Companies House REST API requires you to register an account\n[on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)\nand [configure an API key](https://developer.companieshouse.gov.uk/developer/applications).\nDevelopers should read\n[the Companies House developer guidelines](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/developerGuidelines.html)\nbefore using this API, and will note that these guidelines contain several\ninstructions regarding API keys:\n\n* Do not embed API keys in your code\n* Do not store API keys in your source tree\n* Restrict API key use by IP address and domain\n* **Regenerate your API keys regularly**\n* Delete API keys when no longer required\n\n## Client Initialization\n\nAll requests to the API are made through a client object:\n\n```ruby\nrequire 'companies_house/client'\nclient = CompaniesHouse::Client.new(config)\n```\n\nThe client is configured by passing a hash to the constructor. The supported keys for this\nhash are:\n\n| Key                | Description |\n| ------------------ | ----------- |\n| `:api_key`         | Required. The API key received after registration. |\n| `:endpoint`        | Optional. Specifies the base URI for the API (e.g. if using a self-hosted version) |\n| `:instrumentation` | Optional. Instruments the request/response (see Instrumentation for details) |\n\n## Instrumentation\n\nBy default, no instrumentation is being applied.\nIf you are using Rails or the `ActiveSupport` gem, instrumentation will happen automatically via ![ActiveSupport::Notifications](https://api.rubyonrails.org/classes/ActiveSupport/Notifications.html)\n\n## Requests\n\nOnce a client has been initialised, requests can be made to the API.\nDetails of the available fields in the response are in the Companies House\n[documentation](https://developer.companieshouse.gov.uk/api/docs/index.html).\nThe endpoints currently implemented by the gem are:\n\n| Client Method                                                   | Endpoint                                | Description |\n| --------------------------------------------------------------- | --------------------------------------- | ----------- |\n| `.company(company_number)`                                      | `GET /company/:company_number`          | Retrieves a company profile. |\n| `.officers(company_number)`                                     | `GET /company/:company_number/officers` | Retrieves a list of company officers. |\n| `.company_search(query, items_per_page: nil, start_index: nil)` | `GET /search/companies`                 | Retrieves a list of companies that match the given query. |\n\n### .company\n\nThis method implements the [readCompanyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/readCompanyProfile.html)\nAPI and returns the full [companyProfile](https://developer.companieshouse.gov.uk/api/docs/company/company_number/companyProfile-resource.html)\nresource.\n\n### .officers\n\nThis method implements the [officersList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList.html)\nAPI. It will make one or more requests against this API, as necessary, to obtain\nthe full list of company officers. It returns only the values under the `items`\nkey from the\n[officerList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList-resource.html)\nresource(s) which it reads.\n\n### .company_search\n\nThis method implements the [searchCompanies](https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html)\nAPI and returns the list of [companySearch](https://developer.companieshouse.gov.uk/api/docs/search-overview/CompanySearch-resource.html)\nresources that match the given query. The `items_per_page` and `start_index` parameters are optional.\n\n### .filing_history_list\n\nThis method implements the [filingHistoryList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/getFilingHistoryList.html) API and returns the full [filingHistoryList](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/filingHistoryList-resource.html) resource.\n\n### .filing_history_item\n\nThis method implements the [filingHistoryItem](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/transaction_id/getFilingHistoryItem.html) API and returns the full\n[filingHistoryItem](https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/filingHistoryItem-resource.html) resource.\n\n### Other API Methods\n\nWhile there are other resources exposed by the\n[Companies House API](https://developer.companieshouse.gov.uk/api/docs/index.html),\nthis gem does not implement access to these resources at this time.\n\n## Error Handling\n\nIf a request to the Companies House API encounters an HTTP status other than\n`200 OK`, it will raise an instance of `CompaniesHouse::APIError` instead of\nreturning response data. The error will have the following fields:\n\n| Field      | Description |\n| ---------- | ----------- |\n| `response` | The Net::HTTP response object from the failed API call. |\n| `status`   | A string containing the response status code. |\n\nCertain API responses will raise an instance of a more specific subclass of\n`CompaniesHouse::APIError`:\n\n| Status | Error                                 | Description |\n| ------ | ------------------------------------- | ----------- |\n| 401    | `CompaniesHouse::AuthenticationError` | Authentication error (invalid API key) |\n| 404    | `CompaniesHouse::NotFoundError`       | Not Found. (No record of the company is available.) |\n| 429    | `CompaniesHouse::RateLimitError`      | Application is being [rate limited](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/rateLimiting.html) |\n\nThe client will not catch any other errors which may occur, such as\nerrors involving  network connections (e.g. `Errno::ECONNRESET`).\n\n## Development\n\nThis gem is configured for development using a `bundler` workflow.\nTests are written using RSpec, and Rubocop is used to provide linting.\nBug reports and pull requests are welcome on this project's\n[GitHub repository](https://github.com/gocardless/companies-house-rest).\n\nTo get started:\n\n``` shell\nbundle install --path vendor\n```\n\nTo run all tests and Rubocop:\n\n```shell\nbundle exec rake\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fcompanies-house-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgocardless%2Fcompanies-house-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgocardless%2Fcompanies-house-rest/lists"}