chapi

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.