chapi

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 19, 2021 License: MIT Imports: 8 Imported by: 0

README

chapi

MIT Build Status codecov Go Report Card Used By Godoc

chapi is a Go package providing clients and data structures for working with the Companies House API.

This API consists of:

  • Client — higher-level API, with all methods returning structs.
  • RestClient — lower-level API, all methods return raw JSON bytes.

Because the Companies House API is rate-limited, it may be preferable to use the RestClient and persist the returned data for later use. Resource structs to unmarshal the JSON into can be found in the subpackage ch.

Installation

go get github.com/jimsmart/chapi

import "github.com/jimsmart/chapi"

chapi.APIKey = "your_Companies_House_API_key"

You must provide a valid Companies House API key.

Get an API key
  1. Register a user account with Companies House.
  2. Follow these instructions to get a key.
Keeping your key secret

Either use the key directly in your code, as shown above — or, preferably, keep it outside your code by stashing it externally in your .zshrc (or equivalent). For example:

export COMPANIES_HOUSE_API_KEY=your_Companies_House_API_key

Then get the API key from the environment variable, using code similar to this:

func init() {
    // Get the key from the environment variable.
    apiKey := os.Getenv("COMPANIES_HOUSE_API_KEY")
    if len(apiKey) == 0 {
        panic("COMPANIES_HOUSE_API_KEY environment variable not set")
    }
    // Setting chapi.APIKey provides a default key for all clients.
    // If instead you wish to use a unique key per client, see chapi.NewClientWithKey.
    chapi.APIKey = apiKey
}
Dependencies
  • Standard library.
  • Ginkgo and Gomega if you wish to run the tests.

Example

import "github.com/jimsmart/chapi"

chapi.APIKey = "your_Companies_House_API_key"

func main() {
    ch := chapi.NewClient()
    res, err := ch.Search("Richard Branson", 1, -1)
    if err != nil {
        panic(err)
    }
    // TODO do something with results
}

Documentation

GoDocs https://godoc.org/github.com/jimsmart/chapi

Testing

Package chapi includes a partial test suite but no example code at present - pull requests welcome.

To run the tests execute go test inside the project folder.

License

Package chapi is copyright 2016-2017 by Jim Smart and released under the MIT License

History

  • v0.0.1 (2021-04-19) Use Go modules. Enable CI using GitHub Actions. Remove Travis.

Documentation

Overview

Package chapi provides clients and data structures for working with the Companies House API.

See https://developer.companieshouse.gov.uk/api/docs/

Index

Constants

This section is empty.

Variables

View Source 
var APIKey = ""
View Source 
var BaseURL = "https://api.companieshouse.gov.uk"

BaseURL of Companies House REST API.

View Source 
var DefaultHTTPClient = &http.Client{}

DefaultHTTPClient for requests.

To use an http.Client with different settings, either override this global variable, or instantiate a Client (or RESTClient) instance with the appropriate local configuration.

Functions

This section is empty.

Types

type Client 

type Client struct {
	*RESTClient
}

Client provides higher-level API to access to the Companies House API, with all methods returning unmarshalled JSON structs.

To work with this same API but with raw JSON bytes, see RESTClient.

func NewClient 

func NewClient() *Client

NewClient creats a new instance of Client.

By default, it will use the API key provided by the APIKey package variable and the HTTPClient provided by the DefaultHTTPClient package variable.

func NewClientWithKey 

func NewClientWithKey(apiKey string) *Client

NewClientWithKey creats a new instance of Client, configured to use the given API key and the HTTPClient provided by the DefaultHTTPClient package variable.

func (*Client) CompanyCharge 

func (c *Client) CompanyCharge(companyNumber, chargeID string) (*ch.ChargeDetailsResource, error)

func (*Client) CompanyCharges 

func (c *Client) CompanyCharges(companyNumber string, limit, offset int) (*ch.ChargeListResource, error)

func (*Client) CompanyExemptions 

func (c *Client) CompanyExemptions(companyNumber string) (*ch.CompanyExemptionsResource, error)

func (*Client) CompanyFilingHistory 

func (c *Client) CompanyFilingHistory(companyNumber, categoryFilter string, limit, offset int) (*ch.FilingHistoryListResource, error)

CompanyFilingHistory gets the filing history of the company.

See https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/getFilingHistoryList.html

func (*Client) CompanyFilingHistoryTransaction 

func (c *Client) CompanyFilingHistoryTransaction(companyNumber, transactionID string) (*ch.FilingHistoryItemResource, error)

CompanyFilingHistoryTransaction gets a single item from the filing history of the company.

See https://developer.companieshouse.gov.uk/api/docs/company/company_number/filing-history/transaction_id/getFilingHistoryItem.html

func (*Client) CompanyInsolvency 

func (c *Client) CompanyInsolvency(companyNumber string) (*ch.CompanyInsolvencyResource, error)

CompanyInsolvency gets company insolvency information.

See https://developer.companieshouse.gov.uk/api/docs/company/company_number/insolvency/readCompanyInsolvency.html

func (*Client) CompanyOfficers 

func (c *Client) CompanyOfficers(companyNumber, registerType, sortOrder string, limit, offset int) (*ch.OfficerListResource, error)

CompanyOfficers lists the company officers.

See https://developer.companieshouse.gov.uk/api/docs/company/company_number/officers/officerList.html

func (*Client) CompanyProfile 

func (c *Client) CompanyProfile(companyNumber string) (*ch.CompanyProfileResource, error)

CompanyProfile gets the basic company information.

See https://developer.companieshouse.gov.uk/api/docs/company/company_number/readCompanyProfile.html

func (*Client) CompanyRegisteredOfficeAddress 

func (c *Client) CompanyRegisteredOfficeAddress(companyNumber string) (*ch.RegisteredOfficeAddressResource, error)

CompanyRegisteredOfficeAddress gets the current address of a company.

See https://developer.companieshouse.gov.uk/api/docs/company/company_number/registered-office-address/readRegisteredOfficeAddress.html

func (*Client) CompanyRegisters 

func (c *Client) CompanyRegisters(companyNumber string) (*ch.CompanyRegisterResource, error)

func (*Client) CompanyUKEstablishments 

func (c *Client) CompanyUKEstablishments(companyNumber string) (*ch.CompanyUKEstablishmentsResource, error)

func (*Client) DocumentContent 

func (c *Client) DocumentContent(documentID string) ([]byte, error)

func (*Client) DocumentMetadata 

func (c *Client) DocumentMetadata(documentID string) (*ch.DocumentMetadataResource, error)

func (*Client) OfficerAppointments 

func (c *Client) OfficerAppointments(officerID string, limit, offset int) (*ch.AppointmentListResource, error)

func (*Client) OfficerCorporateDisqualifications 

func (c *Client) OfficerCorporateDisqualifications(officerID string) (*ch.CorporateDisqualificationResource, error)

func (*Client) OfficerNaturalDisqualifications 

func (c *Client) OfficerNaturalDisqualifications(officerID string) (*ch.NaturalDisqualificationResource, error)

func (*Client) PSCCorporateEntity 

func (c *Client) PSCCorporateEntity(companyNumber, pscID string) (*ch.PSCCorporateEntityResource, error)

func (*Client) PSCIndividual 

func (c *Client) PSCIndividual(companyNumber, pscID string) (*ch.PSCIndividualResource, error)

func (*Client) PSCLegalPerson 

func (c *Client) PSCLegalPerson(companyNumber, pscID string) (*ch.PSCLegalPersonResource, error)

func (*Client) PSCStatement 

func (c *Client) PSCStatement(companyNumber, statementID string) (*ch.PSCStatementResource, error)

func (*Client) PSCStatements 

func (c *Client) PSCStatements(companyNumber string, registerView bool, limit, offset int) (*ch.PSCStatementListResource, error)

func (*Client) PSCSuperSecure 

func (c *Client) PSCSuperSecure(companyNumber, superSecureID string) (*ch.PSCSuperSecureResource, error)

func (*Client) PSCs 

func (c *Client) PSCs(companyNumber string, registerView bool, limit, offset int) (*ch.PSCListResource, error)

func (*Client) Search 

func (c *Client) Search(q string, limit, offset int) (*ch.SearchResource, error)

Search performs a query across all Companies House indexed information. To search against specific resource types, see SearchCompanies, SearchOfficers or SearchDisqualifiedOfficers.

Where q is the term being searched for, limit is the number of search results to return 'per page', and offset is the index of the first item to return.

Passing a value of -1 for limit or offset will cause the parameter to be ignored and not sent to the server.

See https://developer.companieshouse.gov.uk/api/docs/search/search.html

func (*Client) SearchCompanies 

func (c *Client) SearchCompanies(q string, limit, offset int) (*ch.CompanySearchResource, error)

SearchCompanies performs a search of company information.

Where q is the term being searched for, limit is the number of search results to return 'per page', and offset is the index of the first item to return.

Passing a value of -1 for limit or offset will cause the parameter to be ignored and not sent to the server.

See https://developer.companieshouse.gov.uk/api/docs/search/companies/companysearch.html

func (*Client) SearchDisqualifiedOfficers 

func (c *Client) SearchDisqualifiedOfficers(q string, limit, offset int) (*ch.DisqualifiedOfficerSearchResource, error)

SearchDisqualifiedOfficers performs a search of disqualified officer information.

Where q is the term being searched for, limit is the number of search results to return 'per page', and offset is the index of the first item to return.

Passing a value of -1 for limit or offset will cause the parameter to be ignored and not sent to the server.

See https://developer.companieshouse.gov.uk/api/docs/search/disqualified-officers/disqualifiedofficersearch.html

func (*Client) SearchOfficers 

func (c *Client) SearchOfficers(q string, limit, offset int) (*ch.OfficerSearchResource, error)

SearchOfficers performs a search of officer information.

Where q is the term being searched for, limit is the number of search results to return 'per page', and offset is the index of the first item to return.

Passing a value of -1 for limit or offset will cause the parameter to be ignored and not sent to the server.

See https://developer.companieshouse.gov.uk/api/docs/search/officers/officersearch.html

type RESTClient 

type RESTClient struct {
	APIKey     string
	HTTPClient *http.Client
}

RESTClient provides low-level access to the Companies House API, with all methods returning the body of the HTTP response in []byte format (raw JSON).

To work with this same API but with unmarshalled JSON structs instead, see Client.

In all methods: should an otherwise successful HTTP request return a response containing a status that is not 2xx or 3xx, an error value of type RESTStatusError will be returned.

func (*RESTClient) CompanyCharge 

func (c *RESTClient) CompanyCharge(companyNumber, chargeID string) ([]byte, error)

func (*RESTClient) CompanyCharges 

func (c *RESTClient) CompanyCharges(companyNumber string, limit, offset int) ([]byte, error)

func (*RESTClient) CompanyExemptions 

func (c *RESTClient) CompanyExemptions(companyNumber string) ([]byte, error)

func (*RESTClient) CompanyFilingHistory 

func (c *RESTClient) CompanyFilingHistory(companyNumber, categoryFilter string, limit, offset int) ([]byte, error)

func (*RESTClient) CompanyFilingHistoryTransaction 

func (c *RESTClient) CompanyFilingHistoryTransaction(companyNumber, transactionID string) ([]byte, error)

func (*RESTClient) CompanyInsolvency 

func (c *RESTClient) CompanyInsolvency(companyNumber string) ([]byte, error)

func (*RESTClient) CompanyOfficers 

func (c *RESTClient) CompanyOfficers(companyNumber, registerType, sortOrder string, limit, offset int) ([]byte, error)

func (*RESTClient) CompanyProfile 

func (c *RESTClient) CompanyProfile(companyNumber string) ([]byte, error)

func (*RESTClient) CompanyRegisteredOfficeAddress 

func (c *RESTClient) CompanyRegisteredOfficeAddress(companyNumber string) ([]byte, error)

func (*RESTClient) CompanyRegisters 

func (c *RESTClient) CompanyRegisters(companyNumber string) ([]byte, error)

func (*RESTClient) CompanyUKEstablishments 

func (c *RESTClient) CompanyUKEstablishments(companyNumber string) ([]byte, error)

func (*RESTClient) DocumentContent 

func (c *RESTClient) DocumentContent(documentID string) ([]byte, error)

func (*RESTClient) DocumentMetadata 

func (c *RESTClient) DocumentMetadata(documentID string) ([]byte, error)

func (*RESTClient) OfficerAppointments 

func (c *RESTClient) OfficerAppointments(officerID string, limit, offset int) ([]byte, error)

func (*RESTClient) OfficerCorporateDisqualifications 

func (c *RESTClient) OfficerCorporateDisqualifications(officerID string) ([]byte, error)

func (*RESTClient) OfficerNaturalDisqualifications 

func (c *RESTClient) OfficerNaturalDisqualifications(officerID string) ([]byte, error)

func (*RESTClient) PSCCorporateEntity 

func (c *RESTClient) PSCCorporateEntity(companyNumber, pscID string) ([]byte, error)

func (*RESTClient) PSCIndividual 

func (c *RESTClient) PSCIndividual(companyNumber, pscID string) ([]byte, error)

func (*RESTClient) PSCLegalPerson 

func (c *RESTClient) PSCLegalPerson(companyNumber, pscID string) ([]byte, error)

func (*RESTClient) PSCStatement 

func (c *RESTClient) PSCStatement(companyNumber, statementID string) ([]byte, error)

func (*RESTClient) PSCStatements 

func (c *RESTClient) PSCStatements(companyNumber string, registerView bool, limit, offset int) ([]byte, error)

func (*RESTClient) PSCSuperSecure 

func (c *RESTClient) PSCSuperSecure(companyNumber, superSecureID string) ([]byte, error)

func (*RESTClient) PSCs 

func (c *RESTClient) PSCs(companyNumber string, registerView bool, limit, offset int) ([]byte, error)

func (*RESTClient) Search 

func (c *RESTClient) Search(q string, limit, offset int) ([]byte, error)

func (*RESTClient) SearchCompanies 

func (c *RESTClient) SearchCompanies(q string, limit, offset int) ([]byte, error)

func (*RESTClient) SearchDisqualifiedOfficers 

func (c *RESTClient) SearchDisqualifiedOfficers(q string, limit, offset int) ([]byte, error)

func (*RESTClient) SearchOfficers 

func (c *RESTClient) SearchOfficers(q string, limit, offset int) ([]byte, error)

type RESTStatusError 

type RESTStatusError struct {
	Status        string
	StatusCode    int
	Body          []byte
	ErrorResource *ch.ErrorResource
}

RESTStatusError is returned as an error value if the http.Response has a StatusCode that is not 2xx or 3xx.

If possible, any content found in the response body is unmarshalled into ErrorResource.

func (*RESTStatusError) Error 

func (e *RESTStatusError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Package ch is a subpackage of package chapi, providing data structures for Companies House API resources.
 Package ch is a subpackage of package chapi, providing data structures for Companies House API resources.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.