API Settings#

The :mod:`ch_api.api_settings` module provides configuration classes for authentication and API endpoints.

API settings and authentication configuration for Companies House API client.

This module provides configuration classes for API endpoints and authentication credentials for the Companies House API client.

The Companies House provides two API environments:

Live API: For production use with real company data
Test/Sandbox API: For development and testing with test data

Authentication:: All API calls require an API key obtained from the Companies House Developer Portal. Register your application at: https://developer.company-information.service.gov.uk/

Example

Configure the client with live API settings:

>>> from ch_api import api_settings
>>> auth = api_settings.AuthSettings(api_key="your-api-key")
>>> # Uses LIVE_API_SETTINGS by default

Use sandbox for testing:

>>> from ch_api import api_settings
>>> auth = api_settings.AuthSettings(api_key="your-test-key")
>>> # client = Client(credentials=auth, settings=api_settings.TEST_API_SETTINGS)

See also

class ch_api.api_settings.AuthSettings(*, api_key: str)[source]#

Bases: object

API key authentication credentials for Companies House API.

The API key serves as your unique identifier and authentication token for all API requests. Treat it as a sensitive credential.

Example

Create authentication settings:

auth = AuthSettings(api_key="your-api-key-here")

Note

API keys can be obtained from https://developer.company-information.service.gov.uk/
Never commit API keys to version control
Use environment variables or secure credential management for production

See also

https: //developer-specs.company-information.service.gov.uk/guides/authorisation

api_key: str#

__init__(*, api_key: str) → None#

class ch_api.api_settings.ApiSettings(*, api_url: str, identity_url: str, test_data_generator_url: str | None = None)[source]#

Bases: object

Configuration for Companies House API endpoints and environments.

This dataclass contains the URLs for different API environments and services. Use LIVE_API_SETTINGS for production or TEST_API_SETTINGS for sandbox testing.

Example

Use predefined settings:

from ch_api import Client, api_settings

# Production settings (default)
client = Client(
    credentials=auth,
    settings=api_settings.LIVE_API_SETTINGS
)

# Sandbox settings for testing
client = Client(
    credentials=test_auth,
    settings=api_settings.TEST_API_SETTINGS
)

See also

LIVE_API_SETTINGS: Production API configuration
TEST_API_SETTINGS: Sandbox API configuration

api_url: str#

identity_url: str#

test_data_generator_url: str | None = None#

__init__(*, api_url: str, identity_url: str, test_data_generator_url: str | None = None) → None#

ch_api.api_settings.LIVE_API_SETTINGS = ApiSettings(api_url='https://api.company-information.service.gov.uk', identity_url='https://identity.company-information.service.gov.uk', test_data_generator_url=None)#

Production API settings for live company data.

Use this for accessing real, up-to-date company information. Requires a valid production API key from Companies House.

API Base: https://api.company-information.service.gov.uk

ch_api.api_settings.TEST_API_SETTINGS = ApiSettings(api_url='https://api-sandbox.company-information.service.gov.uk', identity_url='https://identity-sandbox.company-information.service.gov.uk', test_data_generator_url='https://test-data-sandbox.company-information.service.gov.uk')#

Sandbox/test API settings for development and testing.

Use this environment with test API keys to develop and test your application without affecting production data. The sandbox includes the Test Data Generator service for creating mock companies.

API Base: https://api-sandbox.company-information.service.gov.uk Test Data Generator: https://test-data-sandbox.company-information.service.gov.uk

Note

Test companies created in the sandbox are temporary and not available in the production API.

API Settings#

This Page