Skip to contents

Pull FBI NIBRS offence-event records via Crime Data Explorer

Source: R/ingest_forensics.R
morie_ingest_forensics_nibrs.Rd

Queries the FBI Crime Data Explorer NIBRS endpoint (/crime/fbi/cde/nibrs/<state>/<offense>?year=...). Requires an API key from https://api.data.gov/signup/; pass via api_key= or set the FBI_CDE_API_KEY environment variable. Returns one row per offence-event with nested sub-objects flattened using dotted keys (offense.code, victim.age, ...).

Usage

morie_ingest_forensics_nibrs(
  year,
  offense = NULL,
  state = NULL,
  api_key = NULL,
  max_features = NULL,
  page_size = 500L,
  timeout = .MORIE_FORENSICS_DEFAULT_TIMEOUT
)

Arguments

year

Reporting year (e.g. 2023). Required - CDE forces a year scope.

offense

NIBRS offence slug (e.g. "aggravated-assault", "burglary"); NULL returns all offences.

state

Two-letter US state code (e.g. "GA"). NULL returns the national feed (very large; use max_features).

api_key

FBI CDE API key; falls back to $FBI_CDE_API_KEY.

max_features

Optional hard cap on returned rows.

page_size

CDE page size; server-side cap varies by endpoint.

timeout

HTTP timeout in seconds.

Value

A base R data.frame, one row per offence-event. Without a key the function falls back to the bundled synthetic NIBRS sample (documented schema, toy values) so the open path always works; with a key it queries the live CDE endpoint.

Examples

# \donttest{
# No API key needed: falls back to the bundled synthetic sample.
df <- suppressWarnings(morie_ingest_forensics_nibrs(
  year = 2023, offense = "aggravated-assault", state = "GA",
  max_features = 10L
))
#> morie_ingest_forensics_nibrs: no FBI CDE API key (api_key=/FBI_CDE_API_KEY); returning the bundled synthetic NIBRS sample. Sign up free at https://api.data.gov/signup/ for live data.
head(df)
#>          ori state_abbr offense_code             offense_name data_year
#> 1 SYN0000001         GA          13A       aggravated-assault      2023
#> 2 SYN0000002         GA          220                 burglary      2023
#> 3 SYN0000003         GA          23F theft-from-motor-vehicle      2023
#> 4 SYN0000004         CA          13A       aggravated-assault      2023
#> 5 SYN0000005         CA          220                 burglary      2023
#> 6 SYN0000006         CA          240      motor-vehicle-theft      2023
#>   incident_count
#> 1             42
#> 2             17
#> 3             29
#> 4             88
#> 5             54
#> 6             61
# }