Add company search restrictions parameter

gocardless · Dec 9, 2024 · c02a528 · c02a528
1 parent cb06a07
commit c02a528
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -14,19 +14,19 @@ see the gem [companies-house-gateway](https://github.com/gocardless/companies-ho
 
 Quick start:
 
-* Register an account via the `Sign In / Register` link
-[on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
-* Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications)
-* Put your API key in an environment variable (not in your code):
+- Register an account via the `Sign In / Register` link
+  [on the CompaniesHouse Developers website](https://developer.companieshouse.gov.uk/api/docs/)
+- Register an API key at [Your Applications](https://developer.companieshouse.gov.uk/developer/applications)
+- Put your API key in an environment variable (not in your code):
 
-``` shell
+```shell
 export COMPANIES_HOUSE_API_KEY=YOUR_API_KEY_HERE
 ```
 
-* Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest)
-* Create and use a client:
+- Install `companies-house-rest` through [RubyGems](https://rubygems.org/gems/companies-house-rest)
+- Create and use a client:
 
-``` ruby
+```ruby
 require 'companies_house/client'
 client = CompaniesHouse::Client.new(api_key: ENV['COMPANIES_HOUSE_API_KEY'])
 profile = client.company('07495895')
@@ -52,11 +52,11 @@ Developers should read
 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
+- 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
 
@@ -70,11 +70,11 @@ 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. |
+| 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` | Optional. Instruments the request/response (see Instrumentation for details)       |
 
 ## Instrumentation
 
@@ -88,11 +88,11 @@ Details of the available fields in the response are in the Companies House
 [documentation](https://developer.companieshouse.gov.uk/api/docs/index.html).
 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. |
+| 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, restrictions: nil)` | `GET /search/companies`                 | Retrieves a list of companies that match the given query. |
 
 ### .company
 
@@ -113,7 +113,7 @@ resource(s) which it reads.
 
 This method implements the [searchCompanies](https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html)
 API and returns the list of [companySearch](https://developer.companieshouse.gov.uk/api/docs/search-overview/CompanySearch-resource.html)
-resources that match the given query. The `items_per_page` and `start_index` parameters are optional.
+resources that match the given query. The `items_per_page`, `start_index` and `restrictions` parameters are optional.
 
 ### .filing_history_list
 
@@ -136,22 +136,22 @@ 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 |
-| ---------- | ----------- |
+| Field      | Description                                             |
+| ---------- | ------------------------------------------------------- |
 | `response` | The Net::HTTP response object from the failed API call. |
-| `status`   | A string containing the response status code. |
+| `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.) |
+| 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](https://developer.companieshouse.gov.uk/api/docs/index/gettingStarted/rateLimiting.html) |
 
 The client will not catch any other errors which may occur, such as
-errors involving  network connections (e.g. `Errno::ECONNRESET`).
+errors involving network connections (e.g. `Errno::ECONNRESET`).
 
 ## Development
 
@@ -162,7 +162,7 @@ Bug reports and pull requests are welcome on this project's
 
 To get started:
 
-``` shell
+```shell
 bundle install --path vendor
 ```
 

diff --git a/lib/companies_house/client.rb b/lib/companies_house/client.rb
@@ -80,12 +80,13 @@ def filing_history_item(id, transaction_id)
       )
     end
 
-    def company_search(query, items_per_page: nil, start_index: nil)
+    def company_search(query, items_per_page: nil, start_index: nil, restrictions: nil)
       request(
         resource: :company_search,
         path: "search/companies",
         params: {
-          q: query, items_per_page: items_per_page, start_index: start_index
+          q: query, items_per_page: items_per_page, start_index: start_index,
+          restrictions: restrictions
         }.compact,
       )
     end

diff --git a/spec/companies_house/client_spec.rb b/spec/companies_house/client_spec.rb
@@ -410,6 +410,7 @@
           query,
           items_per_page: items_per_page,
           start_index: start_index,
+          restrictions: restrictions,
         )
       end
 
@@ -418,16 +419,18 @@
           q: query,
           items_per_page: items_per_page,
           start_index: start_index,
+          restrictions: restrictions,
         }
       end
       let(:items_per_page) { 5 }
       let(:start_index) { 3 }
+      let(:restrictions) { "active-companies" }
 
       before do
         stub_request(
           :get,
           "#{example_endpoint}/#{rest_path}?items_per_page=#{items_per_page}\
-&q=#{query}&start_index=#{start_index}",
+&q=#{query}&start_index=#{start_index}&restrictions=#{restrictions}",
         ).
           with(basic_auth: [api_key, ""]).
           to_return(body: '{"companies": "data"}', status: status)