Quickstart

This gets you from install to a computed crash rate in a few lines. It assumes your key is in HUMANBASELINES_API_KEY (see Installation).

Compute a geofence rate

from humanbaselines import HumanBaselines

hb = HumanBaselines()   # api_key from HUMANBASELINES_API_KEY

r = hb.compute(
    county="travis",
    outcome="police_reported",
    ego_vehicle=["cars", "light_trucks"],
    road_type=["arterial", "collector_local"],
)
print(r.rate, r.rate_low, r.rate_high)   # e.g. 4.05 4.0 4.1
print(r.N, r.D_miles, len(r.cells))      # e.g. 24617.0 6.07e9 1795

compute() returns a typed ComputeResult. Omitted filters fall back to the API's defaults (which reproduce the headline numbers in the humanbaselines.com tool).

Pass filters three ways

Keyword args are simplest, but a typed model or a plain dict work identically: all are validated before the request, so a bad value fails fast locally:

from humanbaselines import GeofenceSelections, Outcome

hb.compute(outcome="fatal", road_type=["interstate"])             # kwargs
hb.compute(selections=GeofenceSelections(outcome=Outcome.fatal))  # typed model
hb.compute(selections={"outcome": "fatal"})                       # dict

See Filters for the full catalog.

Discover what you can ask for

Don't hard-code option values; fetch them. The catalog and the available regions are both queryable at runtime:

for f in hb.filters().modes["geofence"]:
    print(f.id, "→", [o.id for o in f.options], "default:", f.default)

for region in hb.regions().regions:
    print(region.county, region.modes)

Route and depot modes

# Rate over interstate (route, milepost) segments:
hb.compute_route(segment_ids=[("I-35", 250), ("I-35", 251)],
                 ego_vehicle=["combination"])

# Full depot-to-depot trip from two (lat, lon) pins:
hb.compute_depot_route(depot_a=(30.25, -97.75), depot_b=(30.40, -97.70),
                       ci_method="fay_feuer")

Handle errors

from humanbaselines import AuthenticationError, ValidationError

try:
    hb.compute(outcome="fatal")
except AuthenticationError:        # 401: bad/missing key
    ...
except ValidationError as e:       # 422: e.errors has field-level detail
    print(e.errors)

Where to go next

• Compute modes: geofence vs route vs depot.
• Configuration: bind and reuse a definition.
• Reference: every method and model.