humanbaselines

Python client for the Human Crash Baselines API: typed access to human-driver crash-rate baselines by region, route, and filter. Created and maintained by Valgo.

It wraps the /v1 REST API behind the humanbaselines.com tool. Construct a client with your key, call typed methods, and get typed results back. The client builds the request bodies and sets the auth header.

pip install humanbaselines

from humanbaselines import HumanBaselines

hb = HumanBaselines(api_key="hbk_...")          # or set HUMANBASELINES_API_KEY

r = hb.compute(region="travis", outcome="police_reported",
               ego_vehicle=["cars", "light_trucks"])
print(r.rate, r.rate_low, r.rate_high)          # 4.05 4.0 4.1

Features

• Typed end to end. Request filters and results are Pydantic models generated from the API's OpenAPI schema, so the client cannot drift from the server.
• Three compute modes. Region-wide geofence rates, interstate route-segment rates, and depot-to-depot trip rates.
• Filters three ways. Keyword args, a typed Selections model, or a plain dict, all validated locally before the request.
• Bound definitions. Bind a methodological definition to a client and reuse it, and serialize it to JSON to version and share.
• Runtime discovery. filters() and regions() return the live catalog of valid values, defaults, and available regions.
• Typed errors. Non-2xx responses raise specific exceptions for auth, validation, and warm-up, with the server's field-level detail.

Next steps

• Installation: install and authenticate.
• Quickstart: computing your first rate.
• Claude Code/Codex: querying from a coding agent.
• Reference: every method, argument, and model.

Learn more

For technical details, read the white paper, and reach out to humanbaselines@valgo.ai to submit feedback or request API access.

Outputs are derived statistics only (rates, counts, bounds). See methodology and licensing.