Quickstart

This 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(
    region="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, a typed model, and a plain dict are equivalent. All are validated before the request, so a bad value fails without a network call:

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.

Discovery

The filter catalog and the available regions are queryable at runtime, so option values need not be hard-coded:

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.region, 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)

Next steps

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