FBI (Uniform) Crime Data API Wrapper

Minimalist FBI Uniform Crime Data (UCR) API Wrapper.

Fulfills most if not all of the functionality indicated by the FBI Uniform Crime Data API found here. Extends additional helpful functionality (optimized performance, additional queries, easier usage).

Basic Usage

require('dotenv').config();

const FBI_Wrapper = require("fbi-ucr-api");
let wrapper = new FBI_Wrapper(process.env.API_KEY);

// Promises

wrapper.getVictimsByORI("MI2802800", "burglary", "age").then((results) => {
  console.log(results);
});

// Asynchronous Function

async function something() {
  let results = await wrapper.getVictimsByState("TX", "burglary", "age");
  console.log(results);
}

Additional examples for how to use these methods can be found in examples/index.js.

For information about how to use a .env file, see documentation for dotenv.

Testing

npm test

// Or if testing running individual category tests:

mocha test/testFileName.js --no-timeouts

Tests check the intended return types and error handling capabilities of functions.

Note: Running all of the tests may take a significant amount of time (roughly 2 minutes) due to all of the GET requests made by the API wrapper.

Additional Remarks

I am aware of the issue where attempting to get arson / crime estimate statistics by region returns undefined. This is a server error on the part of the FBI dataset, and I do not know when it will be resolved.

If anybody knows a better way to do error checking for this API wrapper (without necessitating as many as 4 lines of error checking calls per function), please let me know!

To understand the data provided by this API wrapper, it can be helpful to look at other projects that have used this data. One such (official US Government) project is the FBI's crime data explorer, which visualizes this information.

Find this package on npm here.

This API wrapper is licensed under the MIT License. Feel free to fork and change!

Maintenance may occasionally occur, but don't expect it.

API_DOCUMENTATION

Table of Contents

• constructor
  • Parameters
• getAgencies
• getAgenciesByCoordinates
  • Parameters
• getAgenciesByRegion
  • Parameters
• getAgenciesByState
  • Parameters
• getAgencyByORI
  • Parameters
• getStates
  • Parameters
• getAllStates
• getStatesByRegion
  • Parameters
• getStateByAbbreviation
  • Parameters
• getRegions
• getRegionsByName
  • Parameters
• getPoliceByNation
• getPoliceByRegion
  • Parameters
• getPoliceByState
  • Parameters
• getPoliceByORI
  • Parameters
• getVictimsByNation
  • Parameters
• getVictimsByRegion
  • Parameters
• getVictimsByState
  • Parameters
• getVictimsByORI
  • Parameters
• getOffendersByNation
  • Parameters
• getOffendersByRegion
  • Parameters
• getOffendersByState
  • Parameters
• getOffendersByORI
  • Parameters
• getCrimeCountByNation
  • Parameters
• getCrimeCountByRegion
  • Parameters
• getCrimeCountByState
  • Parameters
• getCrimeCountByORI
  • Parameters
• getCrimesByORI
  • Parameters
• getCrimeByORI
  • Parameters
• getMultipleCrimesByORI
  • Parameters
• getDetailedArsonStatsByNation
• getDetailedArsonStatsByRegion
  • Parameters
• getDetailedArsonStatsByState
  • Parameters
• getParticipationByNation
• getParticipationByRegion
  • Parameters
• getParticipationByState
  • Parameters
• getParticipationByORI
  • Parameters
• getCrimeEstimatesByNation
• getCrimeEstimatesByRegion
  • Parameters
• getCrimeEstimatesByState
  • Parameters

constructor

Creates a new FBI_Wrapper object, which is used to more easily access the FBI UCR API.

Parameters

• userAPIkey String The api.data.gov API key, which is required to access the FBI UCR API. API Keys can be generated here: https://api.data.gov/signup/
• strictErrorChecking Boolean NOW DEPRECATED, DO NOT USE. Disabled error checking by the wrapper. (optional, default true)

getAgencies

Gets information about all agencies in the United States. If desiring to get information about all agencies in the U.S in an array form, consider using getAgenciesByRegion and passing in the "U.S" territories parameter.

Returns Object Information about each agency in the U.S, subdivided into states that are further subdivided into agency objects (identified by their ORI-9 (Department Originating Agency Identifier Number, character length 9)).

getAgenciesByCoordinates

Gets information about all the agencies within range kilometers of the provided coordinates.

Parameters

• latitude Number Desired latitude to center agency search around.
• longitude Number Desired longitude to center agency search around.
• range Number Length (km) of circular radius in which to find agencies. (optional, default 50)

Returns Array Information about all the agencies within range kilometers of the provided coordinates

getAgenciesByRegion

Gets information about all agencies in a specific region. Permitted region numerical codes are 0, 1, 2, 3, 4, 99 Permitted region string names are "U.S. Territories", "Northeast", "Midwest", "South", "West", "Other".

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).

Returns Array Information about all the agencies in that specific region. Undefined if a bad region name is provided.

getAgenciesByState

Gets information about all agencies in a given state

Parameters

• stateAbbreviation String State abbreviation
• pageNumber Number For states with many agencies, data is delivered in multiple "pages", as indicated by the pagination property/object in the returned object. This property allows you to select which page of results you want (Pages are 0-indexed). (optional, default 0)

Returns Object Information about each agency in a given state.

getAgencyByORI

Gets information about a specific agency, as identified by the provided ORI-9. If no ORI is provided, then gets information about all agencies in the United States.

Parameters

• ori String The ORI of the desired agency. (optional, default "")

Returns Object Information about the desired agency, or if no ORI is provided, information about each agency in the U.S.

getStates

Gets identifying information about all the states in the U.S, such as their ID, abbreviation, and region. Expressed in separate pages (20 results per page). If desiring all states at once, use getAllStates()

Parameters

• pageNumber Number Denotes a specific page of results to view, as indicated by the pagination property/object. Each call only returns 20 states at a time. (optional, default 0)

Returns Object Information about (20) states.

getAllStates

Gets identifying information about all the states in the U.S, such as their ID, abbreviation, and region

Returns Array Information about all US states.

getStatesByRegion

Gets identifying information about all states in a specified region

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).

Returns Array Information about all states in that region.

getStateByAbbreviation

Gets identifying information about a specific state based on its abbreviation.

Parameters

• stateAbbreviation String State abbreviation (two characters long, like TX).

Returns Object Identifying information about that state.

getRegions

Gets identifying information about all the regions in the U.S

Returns Array Information about all regions in the U.S

getRegionsByName

Gets identifying information about a specific region based on its name or numerical code.

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).

Returns Object Information about that specific region.

getPoliceByNation

Gets nationwide police employment statistics for each year (up to 1960).

Returns Array Nationwide police employment statistics for each year

getPoliceByRegion

Gets regionwide police employment statistics for each year (up to 1960).

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).

Returns Array Regionwide police employment statistics for each year

getPoliceByState

Gets statewide police employment statistics for each year (up to 1960).

Parameters

• stateAbbreviation String State Abbreviation, two characters long

Returns Array Statewide police employment statistics for each year

getPoliceByORI

Get police employment statistics for a certain agency (hypothetically up the 1960, but many agencies didn't start recording information until later).

Parameters

• ori String The ORI of the desired agency.

Returns Array Agency police employment statistics for each year, in addition to other details about the agency (such as the population that year of the served area).

getVictimsByNation

Given a specific offense and a classification criteria for the victims, returns for each year the number of victims (of said offense) that fall into each category of the classification criteria. This method encompasses nation-wide data. Possible offenses are: "violent_crime", "homicide", "rape-legacy", "rape-revised", "robbery", "aggravated-assault", "property-crime", "burglary", "larceny", "motor-vehicle-theft", and "arson". Possible classifications are: "age", "count", "ethnicity", "race", and "sex". Note that entries are not guaranteed to be in any order, and also be aware that for some years, not all agencies reported data, so data might be skewed from before 2005.

Parameters

• offense String The offense to find victims of.
• classification String The classification criteria by which the victims will be categorized.

Returns Object Entries for each year containing the # of (nation-wide victims of the given offense) in each category type.

getVictimsByRegion

Given a specific offense and a classification criteria for the victims, returns for each year the number of victims (of said offense) that fall into each category of the classification criteria. This method encompasses region-wide data. Additional information can be found under method getVictimsByNation

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).
• offense String The offense to find victims of.
• classification String The classification criteria by which the victims will be categorized.

Returns Object Entries for each year containing the # of (region-wide victims of the given offense) in each category type.

getVictimsByState

Given a specific offense and a classification criteria for the victims, returns for each year the number of victims (of said offense) that fall into each category of the classification criteria. This method encompasses state-wide data. Additional information can be found under method getVictimsByNation

Parameters

• stateAbbreviation String State Abbreviation, two characters long
• offense String The offense to find victims of.
• classification String The classification criteria by which the victims will be categorized.

Returns Object Entries for each year containing the # of (state-wide victims of the given offense) in each category type.

getVictimsByORI

Given a specific offense and a classification criteria for the victims, returns for each year the number of victims (of said offense) that fall into each category of the classification criteria. This method encompasses agency-wide data. Additional information can be found under method getVictimsByNation

Parameters

• ori String The ORI of the agency in question
• offense String The offense to find victims of.
• classification String The classification criteria by which the victims will be categorized.

Returns Object Entries for each year containing the # of (agency-wide victims of the given offense) in each category type.

getOffendersByNation

Given a specific offense and a classification criteria for the offenders, returns for each year the number of offenders (who committed said offense) that fall into each category of the classification criteria. This method encompasses nation-wide data. Additional information can be found under method getVictimsByNation

Parameters

• offense String The offense for which to find offenders.
• classification String The classification criteria by which the offenders will be categorized.

Returns Object Entries for each year containing the # of (nation-wide offenders who committed the given offense) in each category type.

getOffendersByRegion

Given a specific offense and a classification criteria for the offenders, returns for each year the number of offenders (who committed said offense) that fall into each category of the classification criteria. This method encompasses region-wide data. Additional information can be found under method getVictimsByNation

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).
• offense String The offense for which to find offenders.
• classification String The classification criteria by which the offenders will be categorized.

Returns Object Entries for each year containing the # of (region-wide offenders who committed the given offense) in each category type.

getOffendersByState

Given a specific offense and a classification criteria for the offenders, returns for each year the number of offenders (who committed said offense) that fall into each category of the classification criteria. This method encompasses state-wide data. Additional information can be found under method getVictimsByNation

Parameters

• stateAbbreviation String State Abbreviation, two characters long
• offense String The offense for which to find offenders.
• classification String The classification criteria by which the offenders will be categorized.

Returns Object Entries for each year containing the # of (state-wide offenders who committed the given offense) in each category type.

getOffendersByORI

Given a specific offense and a classification criteria for the offenders, returns for each year the number of offenders (who committed said offense) that fall into each category of the classification criteria. This method encompasses agency-wide data. Additional information can be found under method getVictimsByNation

Parameters

• ori String The ORI of the agency in question
• offense String The offense for which to find offenders.
• classification String The classification criteria by which the offenders will be categorized.

Returns Object Entries for each year containing the # of (agency-wide offenders who committed the given offense) in each category type.

getCrimeCountByNation

Given a specific offense, returns for each year the number of incidents and (offense occurrences) that occurred involving that offense. Note that the difference between an incident and an offense is that within an incident, a person could have committed multiple offenses. This method encompasses nation-wide data. Additional information can be found under method getVictimsByNation

Parameters

• offense String The offense for which to find the # of incidents and occurrences.

Returns Array Entries for each year containing the # of incidents and (offense occurrences) involving the given offense

getCrimeCountByRegion

Given a specific offense, returns for each year the number of incidents and (offense occurrences) that occurred involving that offense. This method encompasses region-wide data. Additional information can be found under method getCrimeCountByNation

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).
• offense String The offense for which to find the # of incidents and occurrences.

Returns Array Entries for each year containing the # of incidents and (offense occurrences) involving the given offense

getCrimeCountByState

Given a specific offense, returns for each year the number of incidents and (offense occurrences) that occurred involving that offense. This method encompasses state-wide data. Additional information can be found under method getCrimeCountByNation

Parameters

• stateAbbreviation String State Abbreviation, two characters long
• offense String The offense for which to find the # of incidents and occurrences.

Returns Array Entries for each year containing the # of incidents and (offense occurrences) involving the given offense

getCrimeCountByORI

Given a specific offense, returns for each year the number of incidents and (offense occurrences) that occurred involving that offense. This method encompasses agency-wide data. Additional information can be found under method getCrimeCountByNation

Parameters

• ori String The ORI of the agency in question
• offense String The offense for which to find offenders.

Returns Array Entries for each year containing the # of incidents and (offense occurrences) involving the given offense

getCrimesByORI

Get detailed statistics about the offenses committed within the jurisdiction of a particular agency. If no one type of offense is specified, then this method returns statistics about all types of offenses. If looking for (a) specific offense(s), note that it is much faster to use getCrimeByOri or getMultipleCrimesByORI.

Parameters

• ori String The ORI of the agency in question
• offense String The offense for which to find statistics. If no offense is specified, then get statistics about all offenses. (optional, default "offenses")

Returns (Object | Array) Entries for each year containing detailed statistics about (each offense). If looking up a specific offense, returns an object. Otherwise, returns an array.

getCrimeByORI

Get detailed statistics about an offense committed within the jurisdiction of a particular agency. Transmits more bandwidth, but is significantly faster (2.5x) than relying on the default API exposed by getCrimesByORI.

Parameters

• ori String The ORI of the agency in question.
• offense String The offense for which to find statistics.

Returns Array Entries for each year containing detailed statistics about the offense. Returns undefined if the ORI provided is not valid.

getMultipleCrimesByORI

Get detailed statistics about multiple offenses committed within the jurisdiction of a particular agency. Transmits more bandwidth, but is significantly faster (2.5x) than relying on the default API exposed by getCrimesByORI.

Parameters

• ori String The ORI of the agency in question.
• offenses Array The offenses for which to find statistics.

Returns Array Entries for each year containing detailed statistics about the offenses. Array of arrays, where an index into the returned array matches with that of the offenses array passsed in. Returns undefined if the ORI provided is not valid.

getDetailedArsonStatsByNation

For each year, gets detailed statistics about arson, including the # of reports and estimated property damage. This method encompasses nation-wide data.

Returns Array Entries for each year detailing arson statistics

getDetailedArsonStatsByRegion

For each year, gets detailed statistics about arson, including the # of reports and estimated property damage. Note that this method separates its statistics into states, providing individual arson statistics for each state within the region. This method encompasses region-wide data.

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).

Returns Array Entries for each year detailing arson statistics.

getDetailedArsonStatsByState

For each year, gets detailed statistics about arson, including the # of reports and estimated property damage. This method encompasses state-wide data.

Parameters

• stateAbbreviation String State Abbreviation, two characters long

Returns Array Entries for each year detailing arson statistics.

getParticipationByNation

For each year, returns the total number of agencies in the U.S in addition to what type of data they submit (SRS, NIBRS). SRS is the old hierarchical crime reporting system (Summary Reporting System) that only collects a limited range of data. NIBRS is the new system (National Incident-Based Reporting System) that allows for more extensive data collection (more crime categories).

Returns Array Entries for each year detailing the number of agencies and how many collect what type of information

getParticipationByRegion

For each year, returns the total number of agencies in the specified region in addition to what type of data they submit (SRS, NIBRS).

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).

Returns Array Entries for each year detailing the number of agencies and how many collect what type of information

getParticipationByState

For each year, returns the total number of agencies in the specified state in addition to what type of data they submit (SRS, NIBRS).

Parameters

• stateAbbreviation String State Abbreviation, two characters long

Returns Array Entries for each year detailing the number of agencies and how many collect what type of information

getParticipationByORI

For each year, returns the type of data that this specific agency has been reporting, in addition to other relevant data about the agency.

Parameters

• ori String The ORI of the agency in question

Returns Array Entries for each year detailing the number of agencies and how many collect what type of information

getCrimeEstimatesByNation

For each year, returns the estimated number of crimes (in different categories) that occurred. This method encompasses nation-wide data.

Returns Array Entries for each year detailing the estimated number of crimes that occurred.

getCrimeEstimatesByRegion

For each year, returns the estimated number of crimes (in different categories) that occurred. Note that this method breaks down its statistics into states, providing estimates for each state within the region. This method encompasses region-wide data.

Parameters

• regionName (Number | String) This region's numerical code. Note that this parameter can also be a String (the region's name).

Returns Array Entries for each year detailing the estimated number of crimes that occurred.

getCrimeEstimatesByState

For each year, returns the estimated number of crimes (in different categories) that occurred. This method encompasses state-wide data.

Parameters

• stateAbbreviation String State Abbreviation, two characters long

Returns Array Entries for each year detailing the estimated number of crimes that occurred.