Python SDK

A typed Python client that wraps the REST API. Authentication, retries, batch polling and response parsing are handled for you.

Installation

Using pip

pip install bev-cera

Requires Python 3.10+. The SDK reads the BEV_API_KEY environment variable by default.

Authentication

Set your API key in the environment:

export BEV_CERA_API_KEY="your-api-key"

To override the production API URL for staging or testing:

export BEV_CERA_BASE_URL="https://your-api-host"

Never commit API keys to source control.

Python SDK Usage

In-Depth v2

Use calculate() for both non-cumulative and cumulative perils. Events use EventWithCoords, so each event must provide a non-empty location or both latitude and longitude. A location may also be provided with either coordinate. When dates are omitted, the API defaults start_date to today and end_date to one calendar year after start_date, minus one day.

from bev_cera import Client, EventWithCoords

events = [
    EventWithCoords(
        latitude=51.5,
        longitude=-0.1,
        start_date="2026-01-01",
        end_date="2026-01-01",
    )
]

with Client() as client:
    result = client.in_depth.calculate(perils=["Rain", "Hail"], events=events)
    print(result.results)

Lite scores

from bev_cera import Client

with Client() as client:
    score = client.lite.score(latitude=51.5, longitude=-0.1)
    print(score.scores.root)

Batch

from bev_cera import Client

with Client() as client:
    uploaded = client.batch.upload("events.csv")
    submitted = client.batch.submit(file_id=uploaded.file_id, perils=["Rain"])
    status = client.batch.status(submitted.job_id)
    print(status.progress_percentage, status.processed_rows, status.total_rows)
    result = client.batch.wait_for(submitted.job_id)
    print(result)

batch.submit() generates an idempotency key automatically and reuses it for transport retries. Supply idempotency_key= when the same logical submission may be retried by your own application. Use client.batch.cancel(job_id) to cancel a pending or running job.

Status and completion responses include per-attempt row counts and an integer progress_percentage. The percentage remains below 100 while result artefacts are being finalised and can reset when attempt increments after a worker restart.

Batch uploads are validated client-side before upload. CSVs may contain at most 100,000 data rows and are processed by the API in chunks of 10,000 rows. Large jobs can take several hours, so batch.wait_for() defaults to a 4 hour timeout. Date columns are optional. Missing start_date values default to the job submission date, and missing end_date values default to start_date plus one calendar year minus one day. A CSV containing only a location column is valid.

Error Handling

The python SDK offers typed exceptions to handle your workflow better. The type exceptions currently offered are: AuthenticationError, ValidationError, GeocodingError, RateLimitError, ServerError, ExternalServiceError, TransportError

Async Client

This structures the call as an async client so can be used within an async function. This should not be confused with the batch endpoint which runs asynchronously (where the tasks executes independently without blocking the main flow) but is not a stricly async function using the async/await python syntax. We recommend using the batch job for large tasks as asynchronous programming is in general more prone to errors.

import asyncio

from bev_cera import AsyncClient


async def main() -> None:
    async with AsyncClient() as client:
        perils = await client.perils.list()
        print(perils.daily)


asyncio.run(main())

What the SDK offers over Rest API

CLI Support

Our SDK also comes with CLI support:

pip install "bev-cera[cli]"

Once that has installed you can configure the CLI:

bev-cera configure

(Only Configre the core one time!)

Examples:

bev-cera perils
bev-cera lite --lat 51.5 --lon -0.1
bev-cera in-depth calculate --events events.json --perils Rain,Hail
bev-cera in-depth calculate --events events.json --perils CumulativeRain --window-days 3
bev-cera in-depth daily --events events.json --perils Rain,MaxWindSpeed
bev-cera batch upload events.csv
bev-cera batch run events.csv --perils Rain --no-wait