Metadata-Version: 2.1
Name: ch-api
Version: 1.2.1
Summary: UK Companies House API
Keywords: Companies House,CH,restful api,uk,united kingdom
Author-Email: Ilja Orlovs <VRGhost@users.noreply.github.com>
License: MIT
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Project-URL: Homepage, https://docs.release.art/ch-api/
Project-URL: Documentation, https://docs.release.art/ch-api/
Project-URL: Repository, https://github.com/release-art/ch-api/
Requires-Python: >=3.11
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.12.5
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: ruff>=0.14.13; extra == "dev"
Requires-Dist: myst-parser>=5.0.0; extra == "dev"
Requires-Dist: sphinx>=9.0.4; extra == "dev"
Requires-Dist: sphinx-autobuild>=2025.8.25; extra == "dev"
Requires-Dist: sphinx-copybutton>=0.5.2; extra == "dev"
Requires-Dist: sphinx-design>=0.7.0; extra == "dev"
Requires-Dist: pydata-sphinx-theme>=0.16.1; extra == "dev"
Requires-Dist: autodoc-pydantic>=2.2.0; extra == "dev"
Requires-Dist: pytest-doctestplus>=1.7.1; extra == "dev"
Requires-Dist: pyright>=1.1.408; extra == "dev"
Description-Content-Type: text/markdown

# Companies House API Python Client

[![CI](https://github.com/release-art/ch-api/actions/workflows/ci.yml/badge.svg)](https://github.com/release-art/ch-api/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/ch-api?logo=python&color=41bb13)](https://pypi.org/project/ch-api)

Async Python client for the Companies House API with type-safe Pydantic models, automatic pagination, and comprehensive error handling.

## Features

- Async-first with `httpx`
- Type-safe Pydantic models  
- Automatic pagination handling
- Optional rate limiting
- 98%+ test coverage

## Installation

```bash
pip install ch-api
```

## Quick Start

Example of getting company information:

    >>> async def get_company_example(client):
    ...     company = await client.get_company_profile("09370755")
    ...     return company is not None
    >>> run_async_func(get_company_example)
    True

## Key Endpoints

- **Company**: `get_company_profile()`, `get_officer_list()`, `get_company_psc_list()`, `get_company_charges()`, `get_company_filing_history()`
- **Search**: `search_companies()`, `search_officers()`, `search_disqualified_officers()`
- **Sandbox**: `create_test_company()` (TEST_API_SETTINGS only)

## Pagination

List endpoints return `MultipageList[T]` with `.data` (list) and `.pagination` metadata:

    >>> async def search_example(client):
    ...     results = await client.search_companies("tech", result_count=1)
    ...     return len(results.data) >= 1
    >>> run_async_func(search_example)
    True

## Rate Limiting

The API allows 600 requests per 5 minutes. Use an async rate limiter:

```python doctest
>>> from asyncio_throttle import Throttler  # doctest: +SKIP
```

## Error Handling

```python doctest
>>> import httpx  # doctest: +SKIP
```

## Advanced Usage

### Sandbox Environment

```python doctest
>>> from ch_api import Client, api_settings  # doctest: +SKIP
```

### Custom HTTP Session

```python doctest
>>> import httpx  # doctest: +SKIP
```

## Requirements

- Python 3.11+
- httpx >= 0.28.1
- pydantic >= 2.12.5

## Documentation

- [Full API Docs](https://docs.release.art/ch-api/)
- [API Overview](docs/sources/api-overview.rst)
- [Usage Guide](docs/sources/usage.rst)
- [Contributing](docs/sources/contributing.rst)

## License

[MIT License](LICENSE) - See LICENSE file for details

## Contributing

Please see [CONTRIBUTING](docs/sources/contributing.rst) for development guidelines.


