# aioukcarbon

Async Python client for the [UK Carbon Intensity API](https://carbon-intensity.github.io/api-definitions/).

Data provided by National Energy System Operator (NESO) via the Carbon Intensity API.

## Installation

```bash
pip install aioukcarbon
```

## Usage

```python
import asyncio
from aioukcarbon import CarbonIntensityClient

async def main():
    async with CarbonIntensityClient() as client:
        # Regional intensity by postcode
        regional = await client.get_regional_intensity("DE45")
        print(f"Region: {regional.shortname}")
        print(f"Forecast: {regional.periods[0].intensity.forecast} gCO2eq/kWh")
        print(f"Index: {regional.periods[0].intensity.index}")

        # National intensity
        national = await client.get_national_intensity()
        print(f"National: {national.intensity.forecast} gCO2eq/kWh")

        # Generation mix
        mix = await client.get_generation_mix()
        for fuel in mix.generationmix:
            print(f"  {fuel.fuel}: {fuel.perc}%")

        # 24h regional forecast
        forecast = await client.get_regional_forecast("DE45")
        for period in forecast.periods:
            print(f"  {period.from_time}: {period.intensity.forecast} gCO2eq/kWh")

asyncio.run(main())
```

## API Reference

### `CarbonIntensityClient`

- `get_regional_intensity(postcode)` - Current regional carbon intensity
- `get_regional_forecast(postcode, hours=24)` - Regional forecast (24h or 48h)
- `get_national_intensity()` - Current national carbon intensity
- `get_generation_mix()` - Current national generation mix

### Exceptions

- `CarbonIntensityError` - Base exception
- `CarbonIntensityConnectionError` - Connection failures
- `CarbonIntensityTimeoutError` - Request timeouts
- `CarbonIntensityNoDataError` - No data available for postcode

## License

MIT
