Discovery

Query what the server supports at runtime instead of hard-coding it. These methods return typed models, except manifest and health, which return dicts.

hb.filters()    # FiltersResponse: every filter, its options, per-mode defaults
hb.regions()    # RegionsResponse: regions + the modes each supports
hb.manifest()   # dict: dataset metadata (schema version, row counts)
hb.health()     # dict: service status; needs a Cloud Run base_url (see note)

filters()

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

Each filter exposes id, label, description, affects (n/d/both/rate), multiselect, options ({id, label}), and the per-mode default. See the generated catalog below and the Filters concept page.

regions()

for r in hb.regions().regions:
    print(r.region, r.modes)        # e.g. travis ['geofence', 'route', 'depot']
print(hb.regions().default_region)  # 'travis'

manifest()

Returns dataset metadata: schema_version, generated_at, row_counts, files (with sha256), regions, region_modes, depot_available.

health()

HumanBaselines(api_key="hbk_...",
               base_url="https://human-baseline-api-yz2u5f75wa-uc.a.run.app").health()
# {"status": "ready"}

WARNING

/health is unversioned and is not proxied by humanbaselines.com. Use a Cloud Run base_url for this call. The client raises a clear APIError explaining this if you do not.

Filter catalog

These tables are generated from the API's filter catalog, the same data filters() returns.

Geofence

Filter	Type	Affects	Default	Options	Description
outcome	single-select	n	police_reported	police_reported: Police-reported observed_any_injury: Any reported injury airbag: Any airbag deployment ego_airbag: Ego airbag deployment ka: Serious+ (K or A) fatal: Fatal (K)	What kind of crash to count. Each outcome is a subset of police-reported.
severity	int	n	1	1: 1 2: 2 3: 3 4: 4 5: 5 6: 6 7: 7	Minimum CRIS vehicle-damage rating (1–7) a unit must have to be counted. Ignored for SF (SWITRS records no damage rating).
under_reporting	single-select	n	none	none: None (unadjusted) adjusted: Adjusted (Blincoe et al. 2023)	Apply Blincoe et al. 2023 NHTSA under-reporting multipliers (PDO ×2.48, non-fatal injury ×1.47, fatal ×1.0).
in_transport	single-select	n	in_transport	in_transport: In-transport only include_all: Include parked	Whether to exclude parked vehicles (Vehicle Parked Flag).
desk_reports	single-select	n	exclude	exclude: Exclude desk reports include_all: Include desk reports	Whether to count crashes the driver reported at a police station instead of an officer attending the scene. Excluded by default, because a source that marks the channel is the exception: most states route the driver's own report to a motor-vehicle agency or drop it, so counting them makes a region read high against every other one. A region whose source does not mark the channel has none to exclude and the filter is a no-op there.
ego_vehicle	multi-select	both	cars, light_trucks, heavy_trucks, motorcycles, buses	cars: Cars light_trucks: Light trucks heavy_trucks: Heavy trucks motorcycles: Motorcycles buses: Buses other: Other	Vehicle classes to count and to size the exposure denominator against. Also selects the hourly traffic curve used by time_of_day, since fleets do not share a day.
unresolved_nfs	single-select	both	marginal	marginal: Use observed class share none: Exclude all: Include at full weight	How to treat units whose vehicle class could not be resolved (NFS tier 3).
road_type	multi-select	both	collector_local, arterial, other_freeway, interstate	interstate: Interstate other_freeway: Other freeway / expressway arterial: Arterial collector_local: Collector / local	Functional road classes to include. The dynamic operator multiplier only applies when every selected class is a surface street (arterial / collector_local).
operator_weighting	single-select	rate	region_wide	region_wide: Region-wide robotaxi: Robotaxi	Plain region-wide Σ/Σ rate, or the Chen 2025 operator-weighted spatial multiplier (needs Waymo rider-only mileage). The applied multiplier can be overridden with the operator_weight field. The old value county_wide is still accepted.
multiplier_vmt	single-select	rate	calibrated	calibrated: Calibrated (TxDOT × VM-4) hpms: HPMS (Chen 2025)	Exposure source used inside the operator-weighted multiplier. Only relevant when operator_weighting=robotaxi (and ignored when operator_weight is set explicitly).
denominator_vmt	single-select	d	calibrated	calibrated: CPRD (Caltrans) hpms: HPMS (functional class)	Road-mileage dataset for the rate denominator. Offered where the pipeline built a second denominator to compare against: California (Caltrans CPRD vs HPMS) and Massachusetts (MassDOT per-segment VMT vs HPMS). Texas, Arizona and Nevada have a single state-DOT calibrated denominator and reject 'hpms' with a 400.
tiling	single-select	both	s2	s2: S2 level 13 h3: H3 resolution 8	Spatial cell scheme for the per-cell map and geofence aggregation. 'S2 level 13' (~1.27 sq km) is the default and matches Waymo's CSV4 cells. 'H3 resolution 8' (~0.74 sq km) is an alternative for an H3-native (e.g. Zoox-style) framing; it is preliminary, static-rate only (operator weighting is unavailable), and served only for regions with H3 artifacts built (see /v1/regions tilings).
weather	multi-select	both	any	any: All weather dry: Clear/cloudy rain: Rain fog: Fog winter_storm: Snow & ice	Weather buckets (NOAA-derived). 'any' applies no conditioning, so the denominator is the full VMT with no exposure approximation, and it is the default. The per-bucket options scale VMT by the share of station-hours in that bucket. An hour takes the condition of the station's SCHEDULED report rather than the worst report filed inside it, because the quantity wanted is the share of TIME in a condition and one instant sampled at a fixed offset estimates that without bias. Taking the worst of N reports estimates something larger, and larger the more often a station reports: it inflated rain hours by 1.06x at one report an hour and 1.80x at three. Where a measured traffic factor exists, the hour share is then converted to a share of MILES, since drivers travel less in bad weather: California rain hours carry 0.807 of their proportional traffic, so a rain denominator built from hour shares alone is about 24% too large and its rate correspondingly too low. Factors are measured for California and Pennsylvania; elsewhere the hour share is served unchanged and an adverse-condition rate should be read as a floor. They do not travel: Pennsylvania rain carries 0.956 of its proportional traffic against California's 0.808, because rain is routine there and drivers barely reduce travel for it. The compute response reports which basis was used in weather_exposure_basis. Thunderstorm (WMO 90-96) counts as RAIN, not as snow and ice. No crash source in the tool has a thunderstorm code, so an officer records one as rain, and leaving it on the snow side put hours in that denominator its numerator could never match: it was 22.9% of Philadelphia's snow hours, 99.6% of Houston's, and 100% of San Diego's and Sacramento's, which now report no snow exposure at all and so no rate. The buckets partition: a crash names one condition, so the four rates decompose the unconditioned one. Where a source files two weather fields, both are read and the result is resolved to a single bucket by the same severity rank the station-hours use (snow and ice over rain over fog), because an hour carrying several codes is counted once and the numerator has to match. 'fog' is offered here but the UI does not show it, and its rate should not be used: the officer's fog code and the station's fog report rarely describe the same hour. Joining California crashes to the nearest station's report, an officer coded fog in 4-23% of station-reported fog hours, against 47-59% for rain under the same join, and no visibility threshold closes the gap. The cause is that fog is not a county-scale condition there: two Bay Area stations 16 km apart agree on which hours are foggy only 2-7% of the time, so no officer could agree with the nearest one. Pennsylvania is different and still off: its stations agree on fog 19-36% of the time, but the county files 25 fog crashes a year, too few to check at all. 'winter_storm' is served for Philadelphia and offered but not shown elsewhere. California has too few hours to estimate exposure from, 125 station-hours against a 1,000-hour floor, so its factor is held at a neutral 1.0. Pennsylvania measures 0.753 on 22,420 hours, and its snow code tracks the station's report at 2.44x against a null of 0.99x, so the condition is served there. Because PennDOT publishes no day of month, that check joins a crash to every date in its (month, weekday) and scores the candidate mean, with a California city measured the same way for the reference (see scripts/analyze_weather_code_agreement.py). A list is accepted and its fractions are summed.
light_condition	multi-select	both	any	any: Any daylight: Daylight dawn_dusk: Dawn / dusk dark: Dark	Ambient-light buckets. 'any' disables the filter. Superseded for reviewed regions by time_of_day, which conditions on the same thing with a calibrated denominator; the two cannot be combined. Not offered in the UI, and a light-conditioned rate is uncalibrated: the buckets are shares of station-HOURS, and unlike the weather buckets no mile-share correction has been applied. Dark hours carry substantially less traffic than their share of the clock, so a dark denominator is too large and its rate too low, and daylight errs the other way. The crash-side classification itself is sound: solar geometry reproduces the officer's own light coding on 87.5% of California crashes, with bucket shares matching to 1.6pp. Selecting a light bucket together with a weather bucket multiplies the two shares as though they were independent, which they are not: fog and dark co-occur about 1.36x more often than the product implies.
time_of_day	multi-select	both	any	any: Any h00: 00:00 h01: 01:00 h02: 02:00 h03: 03:00 h04: 04:00 h05: 05:00 h06: 06:00 h07: 07:00 h08: 08:00 h09: 09:00 h10: 10:00 h11: 11:00 h12: 12:00 h13: 13:00 h14: 14:00 h15: 15:00 h16: 16:00 h17: 17:00 h18: 18:00 h19: 19:00 h20: 20:00 h21: 21:00 h22: 22:00 h23: 23:00	Local clock hours, e.g. ["h22","h23","h00"] for a window across midnight. A span is the set of hours in it, so it need not be contiguous. Selecting all 24 collapses to "any", since picking every hour conditions on nothing. The denominator comes from a weather-by-hour joint rather than two marginals multiplied: how often each condition occupies an hour, times how much traffic that hour carries (FHWA TMAS). Weather and hour are dependent by an amount that varies by city, so a product would be wrong by a knowable amount: an overnight hour is 1.23x as likely to be raining as independence implies in the Bay Area, and 0.98x in San Diego. Measured on clock hours rather than on solar darkness, which is entangled with season. Each weather bucket's 24 hours sum back to that bucket's own share, so turning this filter on cannot move a weather-only rate. The traffic curve follows ego_vehicle, blended by the miles the denominator counts for each class: in California heavy trucks drive 18.9% of their miles in 22:00-06:00 against cars' 12.3%, so serving one fleet's curve to another is worth about 1.5x on an overnight rate. The curves are per state: Pennsylvania reads 19.2% and 9.3% for the same two fleets. Two limits: the hour profile is measured statewide, so it carries no local or road-type shape, and it is served only where it has been reviewed. Cannot be combined with light_condition, which partitions the same day differently.
day_type	single-select	both	any	any: Any weekday: Weekday weekend: Weekend	Weekday or weekend, where the weekend runs Friday 18:00 through Monday 05:59. Not the calendar weekend: Friday evening behaves like the weekend and Monday's small hours behave like Sunday night, and this is also the boundary Scanlon et al. (2026) use, which is the only external benchmark for this axis. Selecting both collapses to "any". This shares one denominator with time_of_day rather than multiplying a separate share into it, because the two day types do not have the same shape across the day: a weekend 05:00 hour carries 0.56x what a weekday one does, while midnight carries 1.40x. Their 22:00-06:00 totals agree to 9%, so multiplying marginals would be a no-op across a wide window and about 2x wrong across a narrow one. Because the two arms recombine to the pooled hourly curve exactly, selecting both cannot move a time-of-day answer and selecting neither cannot move anything. Cannot be combined with light_condition, which conditions on the same clock. Served only where hourly exposure has been reviewed.
crash_year	int (multi)	n	2022	2022: 2022 2023: 2023 2024: 2024	Which year(s) of police-reported crash data feed the numerator. Geofence cities only (their units carry a crash_year column). Selecting multiple years pools their crashes and scales the denominator by the number of years, so the rate stays an annual mean. The listed years are advertised, not region-validated; years absent from a region are silently ignored.

Route

Filter	Type	Affects	Default	Options	Description
outcome	single-select	n	police_reported	police_reported: Police-reported observed_any_injury: Any reported injury airbag: Any airbag deployment ego_airbag: Ego airbag deployment ka: Serious+ (K or A) fatal: Fatal (K)	What kind of crash to count. Each outcome is a subset of police-reported.
severity	int	n	1	1: 1 2: 2 3: 3 4: 4 5: 5 6: 6 7: 7	Minimum CRIS vehicle-damage rating (1–7) a unit must have to be counted. Ignored for SF (SWITRS records no damage rating).
under_reporting	single-select	n	none	none: None (unadjusted) adjusted: Adjusted (Blincoe et al. 2023)	Apply Blincoe et al. 2023 NHTSA under-reporting multipliers (PDO ×2.48, non-fatal injury ×1.47, fatal ×1.0).
in_transport	single-select	n	in_transport	in_transport: In-transport only include_all: Include parked	Whether to exclude parked vehicles (Vehicle Parked Flag).
ego_vehicle	multi-select	both	combination	cars: Cars light_trucks: Light trucks combination: Combination trucks (Class 8 / tractor-trailer) motorcycles: Motorcycles buses: Buses other: Other	Vehicle classes to count and to size the exposure denominator against.
unresolved_nfs	single-select	both	marginal	marginal: Use observed class share none: Exclude all: Include at full weight	How to treat units whose vehicle class could not be resolved (NFS tier 3).
weather	multi-select	both	any	any: All weather dry: Clear/cloudy rain: Rain fog: Fog winter_storm: Snow & ice	Weather buckets (NOAA-derived). 'any' applies no conditioning, so the denominator is the full VMT with no exposure approximation, and it is the default. The per-bucket options scale VMT by the share of station-hours in that bucket. An hour takes the condition of the station's SCHEDULED report rather than the worst report filed inside it, because the quantity wanted is the share of TIME in a condition and one instant sampled at a fixed offset estimates that without bias. Taking the worst of N reports estimates something larger, and larger the more often a station reports: it inflated rain hours by 1.06x at one report an hour and 1.80x at three. Where a measured traffic factor exists, the hour share is then converted to a share of MILES, since drivers travel less in bad weather: California rain hours carry 0.807 of their proportional traffic, so a rain denominator built from hour shares alone is about 24% too large and its rate correspondingly too low. Factors are measured for California and Pennsylvania; elsewhere the hour share is served unchanged and an adverse-condition rate should be read as a floor. They do not travel: Pennsylvania rain carries 0.956 of its proportional traffic against California's 0.808, because rain is routine there and drivers barely reduce travel for it. The compute response reports which basis was used in weather_exposure_basis. Thunderstorm (WMO 90-96) counts as RAIN, not as snow and ice. No crash source in the tool has a thunderstorm code, so an officer records one as rain, and leaving it on the snow side put hours in that denominator its numerator could never match: it was 22.9% of Philadelphia's snow hours, 99.6% of Houston's, and 100% of San Diego's and Sacramento's, which now report no snow exposure at all and so no rate. The buckets partition: a crash names one condition, so the four rates decompose the unconditioned one. Where a source files two weather fields, both are read and the result is resolved to a single bucket by the same severity rank the station-hours use (snow and ice over rain over fog), because an hour carrying several codes is counted once and the numerator has to match. 'fog' is offered here but the UI does not show it, and its rate should not be used: the officer's fog code and the station's fog report rarely describe the same hour. Joining California crashes to the nearest station's report, an officer coded fog in 4-23% of station-reported fog hours, against 47-59% for rain under the same join, and no visibility threshold closes the gap. The cause is that fog is not a county-scale condition there: two Bay Area stations 16 km apart agree on which hours are foggy only 2-7% of the time, so no officer could agree with the nearest one. Pennsylvania is different and still off: its stations agree on fog 19-36% of the time, but the county files 25 fog crashes a year, too few to check at all. 'winter_storm' is served for Philadelphia and offered but not shown elsewhere. California has too few hours to estimate exposure from, 125 station-hours against a 1,000-hour floor, so its factor is held at a neutral 1.0. Pennsylvania measures 0.753 on 22,420 hours, and its snow code tracks the station's report at 2.44x against a null of 0.99x, so the condition is served there. Because PennDOT publishes no day of month, that check joins a crash to every date in its (month, weekday) and scores the candidate mean, with a California city measured the same way for the reference (see scripts/analyze_weather_code_agreement.py). A list is accepted and its fractions are summed.
light_condition	multi-select	both	any	any: Any daylight: Daylight dawn_dusk: Dawn / dusk dark: Dark	Ambient-light buckets. 'any' disables the filter. Superseded for reviewed regions by time_of_day, which conditions on the same thing with a calibrated denominator; the two cannot be combined. Not offered in the UI, and a light-conditioned rate is uncalibrated: the buckets are shares of station-HOURS, and unlike the weather buckets no mile-share correction has been applied. Dark hours carry substantially less traffic than their share of the clock, so a dark denominator is too large and its rate too low, and daylight errs the other way. The crash-side classification itself is sound: solar geometry reproduces the officer's own light coding on 87.5% of California crashes, with bucket shares matching to 1.6pp. Selecting a light bucket together with a weather bucket multiplies the two shares as though they were independent, which they are not: fog and dark co-occur about 1.36x more often than the product implies.
driver_impairment	single-select	n	any	any: Any exclude_impaired: Exclude impaired impaired_only: Impaired only	Filter by driver-impairment coding. Route and depot modes only.
ci_method	single-select	rate	fay_feuer	fay_feuer: Fay-Feuer (weighted Poisson) empirical_bayes: Empirical Bayes (Gamma-Poisson)	Method for the 95% CI in route / depot modes.

Depot

Filter	Type	Affects	Default	Options	Description
outcome	single-select	n	police_reported	police_reported: Police-reported observed_any_injury: Any reported injury airbag: Any airbag deployment ego_airbag: Ego airbag deployment ka: Serious+ (K or A) fatal: Fatal (K)	What kind of crash to count. Each outcome is a subset of police-reported.
severity	int	n	1	1: 1 2: 2 3: 3 4: 4 5: 5 6: 6 7: 7	Minimum CRIS vehicle-damage rating (1–7) a unit must have to be counted. Ignored for SF (SWITRS records no damage rating).
under_reporting	single-select	n	none	none: None (unadjusted) adjusted: Adjusted (Blincoe et al. 2023)	Apply Blincoe et al. 2023 NHTSA under-reporting multipliers (PDO ×2.48, non-fatal injury ×1.47, fatal ×1.0).
in_transport	single-select	n	in_transport	in_transport: In-transport only include_all: Include parked	Whether to exclude parked vehicles (Vehicle Parked Flag).
ego_vehicle	multi-select	both	combination	cars: Cars light_trucks: Light trucks combination: Combination trucks (Class 8 / tractor-trailer) motorcycles: Motorcycles buses: Buses other: Other	Vehicle classes to count and to size the exposure denominator against.
unresolved_nfs	single-select	both	marginal	marginal: Use observed class share none: Exclude all: Include at full weight	How to treat units whose vehicle class could not be resolved (NFS tier 3).
weather	multi-select	both	any	any: All weather dry: Clear/cloudy rain: Rain fog: Fog winter_storm: Snow & ice	Weather buckets (NOAA-derived). 'any' applies no conditioning, so the denominator is the full VMT with no exposure approximation, and it is the default. The per-bucket options scale VMT by the share of station-hours in that bucket. An hour takes the condition of the station's SCHEDULED report rather than the worst report filed inside it, because the quantity wanted is the share of TIME in a condition and one instant sampled at a fixed offset estimates that without bias. Taking the worst of N reports estimates something larger, and larger the more often a station reports: it inflated rain hours by 1.06x at one report an hour and 1.80x at three. Where a measured traffic factor exists, the hour share is then converted to a share of MILES, since drivers travel less in bad weather: California rain hours carry 0.807 of their proportional traffic, so a rain denominator built from hour shares alone is about 24% too large and its rate correspondingly too low. Factors are measured for California and Pennsylvania; elsewhere the hour share is served unchanged and an adverse-condition rate should be read as a floor. They do not travel: Pennsylvania rain carries 0.956 of its proportional traffic against California's 0.808, because rain is routine there and drivers barely reduce travel for it. The compute response reports which basis was used in weather_exposure_basis. Thunderstorm (WMO 90-96) counts as RAIN, not as snow and ice. No crash source in the tool has a thunderstorm code, so an officer records one as rain, and leaving it on the snow side put hours in that denominator its numerator could never match: it was 22.9% of Philadelphia's snow hours, 99.6% of Houston's, and 100% of San Diego's and Sacramento's, which now report no snow exposure at all and so no rate. The buckets partition: a crash names one condition, so the four rates decompose the unconditioned one. Where a source files two weather fields, both are read and the result is resolved to a single bucket by the same severity rank the station-hours use (snow and ice over rain over fog), because an hour carrying several codes is counted once and the numerator has to match. 'fog' is offered here but the UI does not show it, and its rate should not be used: the officer's fog code and the station's fog report rarely describe the same hour. Joining California crashes to the nearest station's report, an officer coded fog in 4-23% of station-reported fog hours, against 47-59% for rain under the same join, and no visibility threshold closes the gap. The cause is that fog is not a county-scale condition there: two Bay Area stations 16 km apart agree on which hours are foggy only 2-7% of the time, so no officer could agree with the nearest one. Pennsylvania is different and still off: its stations agree on fog 19-36% of the time, but the county files 25 fog crashes a year, too few to check at all. 'winter_storm' is served for Philadelphia and offered but not shown elsewhere. California has too few hours to estimate exposure from, 125 station-hours against a 1,000-hour floor, so its factor is held at a neutral 1.0. Pennsylvania measures 0.753 on 22,420 hours, and its snow code tracks the station's report at 2.44x against a null of 0.99x, so the condition is served there. Because PennDOT publishes no day of month, that check joins a crash to every date in its (month, weekday) and scores the candidate mean, with a California city measured the same way for the reference (see scripts/analyze_weather_code_agreement.py). A list is accepted and its fractions are summed.
light_condition	multi-select	both	any	any: Any daylight: Daylight dawn_dusk: Dawn / dusk dark: Dark	Ambient-light buckets. 'any' disables the filter. Superseded for reviewed regions by time_of_day, which conditions on the same thing with a calibrated denominator; the two cannot be combined. Not offered in the UI, and a light-conditioned rate is uncalibrated: the buckets are shares of station-HOURS, and unlike the weather buckets no mile-share correction has been applied. Dark hours carry substantially less traffic than their share of the clock, so a dark denominator is too large and its rate too low, and daylight errs the other way. The crash-side classification itself is sound: solar geometry reproduces the officer's own light coding on 87.5% of California crashes, with bucket shares matching to 1.6pp. Selecting a light bucket together with a weather bucket multiplies the two shares as though they were independent, which they are not: fog and dark co-occur about 1.36x more often than the product implies.
driver_impairment	single-select	n	any	any: Any exclude_impaired: Exclude impaired impaired_only: Impaired only	Filter by driver-impairment coding. Route and depot modes only.
ci_method	single-select	rate	empirical_bayes	fay_feuer: Fay-Feuer (weighted Poisson) empirical_bayes: Empirical Bayes (Gamma-Poisson)	Method for the 95% CI in route / depot modes.

Region / mode matrix

Region	Geofence	Route	Depot
travis	✅	-	-
houston	✅	-	-
sanantonio	✅	-	-
dallas	✅	-	-
sf	✅	-	-
la	✅	-	-
phoenix	✅	-	-
vegas	✅	-	-
sandiego	✅	-	-
sacramento	✅	-	-
philadelphia	✅	-	-
boston	✅	-	-
cambridge	✅	-	-
worcester	✅	-	-
dc	✅	-	-
polk	✅	-	-
johnson	✅	-	-
chicago	✅	-	-
interstates	-	✅	✅