HumanBaselines client

The HumanBaselines class is the entry point. Construct it once with your key, then call its compute and discovery methods.

from humanbaselines import HumanBaselines

hb = HumanBaselines(api_key="hbk_...")

Constructor

HumanBaselines(
    api_key: str | None = None,
    *,
    base_url: str = "https://humanbaselines.com",
    timeout: float = 30.0,
    max_retries: int = 2,
    session: requests.Session | None = None,
    config: dict | str | Path | None = None,
)

Argument	Default	Notes
api_key	$HUMANBASELINES_API_KEY	Sent as the X-API-Key header. Raises ValueError if neither is set.
base_url	https://humanbaselines.com	API host. Proxies /v1/*. Point at the Cloud Run URL for non-/v1 paths like health().
timeout	30.0	Per-request timeout, seconds.
max_retries	2	Automatic retries with exponential backoff on 502/503/504 (handles cold-start warm-up).
session	new requests.Session	Bring your own session if you need custom transport.
config	None	A bound definition: a dict of county + filter fields, or a path to a JSON file from save_config. Validated here, so bad fields fail fast.

Methods

Method	Purpose
compute(...)	Geofence (S2-cell) crash rate.
compute_route(...)	Rate over interstate (route, milepost) segments.
compute_depot_route(...)	Full depot-to-depot trip rate.
filters()	Catalog of filters, options, and per-mode defaults.
regions()	Regions available and the modes each supports.
manifest()	Dataset metadata.
health()	Service status (needs a Cloud Run base_url).
config() / changes() / with_config() / save_config() / from_config()	Bound-definition helpers.

Lifecycle

HumanBaselines is a context manager; the underlying session closes on exit:

with HumanBaselines() as hb:
    print(hb.compute().rate)

Or call hb.close() explicitly. repr(hb) shows the base URL and any bound config.