An R wrapper for the FBI Crime Data Explorer (CDE) API providing access to UCR and NIBRS crime data. The package offers a unified interface for querying summarized crime statistics, arrest demographics, NIBRS incident-level data, Supplemental Homicide Reports (SHR), and police employment statistics.
All network requests go through cde_request(), the single network seam
for the package. No API key is required for the current CDE host at
cde.ucr.cjis.gov.
fbiCDE is distributed through r-universe, not CRAN. Install the released version with:
install.packages(
"fbiCDE",
repos = c("https://civilytics.r-universe.dev", "https://cloud.r-project.org")
)or the development version from GitHub:
remotes::install_github("civilytics/fbi_cde")library(fbiCDE)
# Get all states available in the API
get_states()
# Get offense codes
get_offense_codes()
# Get summarized crime data for a specific agency
get_agency_crime("CA0010900")
# Get arrest demographics for a state
get_arrest_demographics(state_abb = "CA")- Reported: the sum of what agencies submitted to the FBI, in either
format (NIBRS, or the older summary format).
get_reported_crime(). - Estimated: the FBI’s published figure, which adds a model’s
prediction for everything outside NIBRS, with a 95% confidence
interval.
get_nibrs_estimate(), for 2021 and 2022. - Imputed: a value filled in for a missing report, by the FBI’s
model or by
impute_reporting_gaps().
imputation_gap() shows how much of the FBI’s published figure its
model supplied. See vignette("estimates").
Functions for retrieving reference data from the CDE API.
| Function | Description |
|---|---|
get_agencies() |
Get all agencies from the CDE API |
get_offense_codes() |
Get offense codes from the CDE API |
get_states() |
Get state list from the CDE API |
# List all states
get_states()
# List offense codes
get_offense_codes()
# Get all agencies (may take a moment)
agencies <- get_agencies()Functions for querying UCR Offenses Known and Clearances data.
| Function | Description |
|---|---|
get_agency_crime() |
Get agency-level crime data |
get_reported_crime() |
Get state- or national-level reported crime counts |
get_reported_arson() |
Get state- or national-level reported arson counts |
get_nibrs_estimate() |
Get the FBI’s published NIBRS estimates, 2021-2022 |
imputation_gap() |
How much of the FBI’s published figure was estimated |
# Agency-level crime data (violent crime)
get_agency_crime("CA0010900")
# State-level reported crime
get_reported_crime("CA")
# National-level reported crime
get_reported_crime()
# Reported arson for a state
get_reported_arson("CA")
# How much of California's published violent crime was modeled
imputation_gap("CA", year = 2021:2022)Functions for querying UCR arrest statistics.
| Function | Description |
|---|---|
get_arrest_count() |
Monthly arrests, for all offenses or one |
get_arrest_demographics() |
Arrestees by sex, race and age, for all offenses or one |
get_arrest_demographics_all() |
Deprecated alias of get_arrest_demographics() |
list_ucr_arrest_offenses() |
The offense names those functions accept |
# Total arrests for an agency
get_arrest_count(ori = "CA0010900")
# One offense, monthly
get_arrest_count(state_abb = "CA", offense = "Robbery")
# Arrestees by sex, race and age, for one offense
get_arrest_demographics(state_abb = "CA", offense = "Larceny")
# The offense names they accept
list_ucr_arrest_offenses()Functions for querying National Incident-Based Reporting System data.
| Function | Description |
|---|---|
get_nibrs_victim() |
Get victim-level NIBRS data |
get_nibrs_offender() |
Get offender-level NIBRS data |
get_nibrs_offense() |
Get offense-level NIBRS data |
list_nibrs_offenses() |
List all NIBRS offense codes |
list_nibrs_victim_variables() |
List victim variable options |
list_nibrs_offender_variables() |
List offender variable options |
list_nibrs_offense_variables() |
List offense variable options |
list_regions() |
List all region choices |
# Victim demographics (race)
get_nibrs_victim(state_abb = "OH", offense = "ROB", variable = "race",
from = "01-2023", to = "12-2023")
# Offender demographics
get_nibrs_offender(state_abb = "OH", offense = "BUR", variable = "age",
from = "01-2023", to = "12-2023")
# Offense characteristics (weapons)
get_nibrs_offense(state_abb = "OH", offense = "ROB", variable = "weapons",
from = "01-2023", to = "12-2023")Functions for querying Supplemental Homicide Reports data.
| Function | Description |
|---|---|
get_shr() |
Get SHR homicide offense counts |
# National-level SHR data
get_shr()
# California state-level SHR data
get_shr(state_abb = "CA")Functions for querying police staffing data.
| Function | Description |
|---|---|
get_police_employment() |
Get police staffing data |
# Oakland PD staffing
get_police_employment("CA0010900", from = "2018", to = "2020")
# California, and the nation
get_police_employment(state_abb = "CA", from = "2018", to = "2020")
get_police_employment(from = "2018", to = "2020")Helper functions for working with the CDE API.
| Function | Description |
|---|---|
cde_base_url() |
Get the CDE API base URL |
cde_path() |
Build a CDE API path string |
cde_query() |
Build query parameters for CDE requests |
is_valid_ori() |
Validate an ORI code |
is_valid_state() |
Validate a state abbreviation |
# Check the base URL
cde_base_url()
#> [1] "https://cde.ucr.cjis.gov/LATEST/"
# Build a path
cde_path("summarized", "national", "V")
#> [1] "summarized/national/V"
# Build query params
cde_query("01-2015", "12-2020", type = "counts")
#> $from
#> [1] "01-2015"
#> $to
#> [1] "12-2020"
#> $type
#> [1] "counts"
# Validate an ORI
is_valid_ori("CA0010900")
#> [1] TRUE
# Validate a state
is_valid_state("CA")
#> [1] TRUEThe package uses cde_request() as its single network seam. All API
calls route through this function, which:
- Builds the full URL from
cde_base_url()+cde_path()+cde_query() - Performs the HTTP GET request via
httr::GET, retrying transient failures - Parses the JSON response via
jsonlite::fromJSON() - Returns a list for downstream parsing
Tests mock cde_request() itself, so the whole suite runs offline. Live
tests against the real API run only when FBI_CDE_LIVE=true is set:
FBI_CDE_LIVE=true NOT_CRAN=true Rscript -e 'testthat::test_local()'Network errors and HTTP 408, 429 and 5xx responses are retried with
exponential backoff (honouring Retry-After). Two options tune this:
options(fbiCDE.max_retries = 3) # retries after the first attempt; 0 disables
options(fbiCDE.timeout = 60) # seconds allowed per attemptAll data is sourced from the FBI Crime Data Explorer API at https://cde.ucr.cjis.gov/LATEST/. No API key is required for the current host.
See the full package documentation for detailed function reference and parameter descriptions.