In elipousson/crashapi: CrashAPI

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

crashapi

The goal of the crashapi R package is to provide functions for downloading data from the National Highway Traffic Safety Administration (NHTSA) Fatality Analysis Reporting System (FARS) API.

What is FARS? NHTSA explains: "The Fatality Analysis Reporting System (FARS) contains data on all vehicle crashes in the United States that occur on a public roadway and involve a fatality."

Installation

You can install the development version of crashapi using the pak package:

pak::pkg_install("elipousson/crashapi")

Background

Fatality Analysis Reporting System (FARS) API support

Supported APIs for this package include:

[x] Get Crash List Information
[X] Get Crash Details
[x] Get Crashes By Location
[X] Get Crashes By Vehicle
[x] Get Summary Counts
[x] Get Variables and Get Variable Attributes
[x] Get FARS Data By Year
[X] Get Crashes By Occupant (partial support)

Most of these APIs support XML, JSV, CSV, and JSON output formats. This package only uses JSON with the exception of get_fars_year() (which supports downloading CSV files).

For reference, this package also includes a list of terms and NHTSA technical definitions in fars_terms and a list of variable labels in fars_vars_labels.

The FARS API currently provides access to data from 2010 to 2022. The NHTSA website also provides additional information on the release data and version status for the FARS data files available through the API:

| Data Year | File Version | Release Date | |-----------|--------------|-------------------| | 2010 | Final | December 11, 2012 | | 2011 | Final | November 13, 2013 | | 2012 | Final | December 12, 2013 | | 2013 | Final | December 14, 2014 | | 2014 | Final | December 18, 2015 | | 2015 | Final | December 16, 2016 | | 2016 | Final | December 14, 2017 | | 2017 | Final | December 18, 2018 | | 2018 | Final | June 24, 2021 | | 2019 | Final | March 2, 2022 | | 2020 | Final | April 3, 2023 | | 2021 | Final | August 19, 2024 | | 2022 | Annual | August 19, 2024 |

Additional data access functionality

The get_fars_zip() function can be used to access FARS data files from 1975 to 2020 that that are not available via the API but are available for download on through the NHTSA File Downloads site as zipped CSV or SAS files (not available through the NHTSA FARS API). This site also provides extensive technical documentation on coding and use of the FARS data files.

Earlier data along with data from the the General Estimates System (GES) / Crash Report Sampling System (CRSS) is also available through the Fatality and Injury Reporting System Tool (FIRST).

Examples

library(crashapi)
library(ggplot2)

Most features for the package can be accessed using the get_fars() function that selects the appropriate API-specific function based on the provided parameters. You can also set the API to use with the api parameter or use an API-specific function (e.g. get_fars_summary()).

For example, you can use the get_fars() access state-level summary data on crash and fatality counts.

# Get summary crash count and fatality count data for Maryland from 2010 to 2019
md_summary <-
  get_fars(
    year = c(2010, 2021),
    state = "MD",
    api = "summary count"
  )

ggplot(md_summary, aes(x = CaseYear, y = TotalFatalCounts)) +
  geom_point(color = "red") +
  geom_line(color = "red", group = 1) +
  theme_minimal()

You can download crash data and set geometry to TRUE optionally convert the data frame into an sf object for mapping.

crashes_sf <-
  get_fars(
    year = c(2018, 2021),
    state = "NC",
    county = "Wake County",
    geometry = TRUE
  )

nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"))
wake_co <- sf::st_transform(nc[nc$NAME == "Wake", ], 4326)

# Map crashes
ggplot() +
  geom_sf(
    data = wake_co,
    fill = NA, color = "black"
  ) +
  geom_sf(
    data = sf::st_crop(crashes_sf, wake_co),
    aes(color = TOTALVEHICLES),
    alpha = 0.75
  ) +
  theme_void()

You can list crashes and filter by the number of vehicles involved.

# Get fatal crashes in New York state from 2019 with 5 to 10 vehicles
get_fars(
  year = 2019,
  state = "NY",
  vehicles = c(5, 10)
)

If you call get_fars() or get_fars_crashes() with details set to TRUE, additional information from get_fars_cases() (including the crash date and time) is appended to the crash data frame.

# Get fatal crashes for Anne Arundel County, MD for 2019 and append details
crashes_detailed <-
  get_fars(
    year = 2019,
    state = "MD",
    county = "Anne Arundel County",
    details = TRUE
  )

# Show 10 fatal crashes at random
dplyr::slice_sample(crashes_detailed, n = 10)

Related packages and projects

rfars aims to "simplify the process of analyzing FARS data" by providing access to FARS downloads and preprocessed data back to 2015.
stats19 "provides functions for downloading and formatting road crash data" from "the UK's official road traffic casualty database, STATS19."
njtr1: "An R interface to New Jersey traffic crash data reported on form NJTR-1."
wisdotcrashdatabase: "A package used for internal WisDOT crash database pulls and analysis."
nzcrash: "An R package to distribute New Zealand crash data in a convenient form."
GraphHopper Open Traffic Collection: "Collections of URLs pointing to traffic information portals which contain open data or at least data which is free to use."
Open Crash Data Index: A Google Sheet listing a range of city, county, regional and state sources for crash data including non-injury crashes as well as the fatal crashes available through the FARS API. Contributions for crash data from other U.S. cities and states are welcome.