Crime Data Explorer

This project is the front end for the Crime Data Explorer, using data from fbi-cde/crime-data-api. The Crime Data Explorer is a website that allows law enforcement and the general public to more easily access Uniform Crime Reporting (UCR) data. Over 18,000 city, university and college, county, state, tribal, and federal law enforcement agencies voluntarily report crime data to the program, and the FBI publishes it in annual reports.

Using the API Directly

API Base URL: https://api.usa.gov/crime/fbi/sapi

Requests Format: https://api.usa.gov/crime/fbi/sapi/{desired_endpiont}?api_key=<API_KEY>

See more information about API endpoints at https://crime-data-explorer-master.fr.cloud.gov/api API Requests are required to have an API Key appended to the request to sign up for an API key please vist https://api.data.gov/signup/

Example Requests:

• https://api.usa.gov/crime/fbi/sapi/api/participation/national?api_key=XXX
• https://api.usa.gov/crime/fbi/sapi/api/agencies?api_key=iiHnOKfno2Mgkt5AynpvPpUQTEyxE77jo1RU8PIv

Installation

You will need node and npm to install and run this project.

1. git clone [email protected]:fbi-cde/crime-data-frontend.git cde && cd cde
2. npm install

Running the app locally

The application expects a few environment variables to interact with the API:

• CDE_API - this should be the URL for the API. To use the public API, set this to https://api.usa.gov/crime/fbi/sapi
• API_KEY - this should match the key used by the API. If you are using the public API, sign up for an API key at https://api.data.gov/signup/

You can copy the env.sample file (cp env.sample .env), fill in your own values, and then make sure to source .env before running the build process.

Use npm run watch to start the continuous webpack processes and a webserver.

Running tests

You can lint the code with npm run lint and run tests with npm run test.

Running Selenium tests

1. Launch Selenium Stand-alone server with npm run selenium:start or npm run selenium:start:mac on a Mac. You will want to start this in a different shell or as a background task.
2. Ensure CDE is running locally
3. Configure test/browser/release_verification.js to use the port you have CDE running on
4. Execute npm run selenium:run - This will execute the automated test that covers the manual verification process

Updating agency data

We load a JSON file, sourced from the API, into the application that has all the agency ORIs and names to make the end user experience better. When we need to update that JSON file with new data from the API, we can just run npm run agencies and the data will be downloaded and gzipped properly. This is useful when agency names are updated.

Deployment

master branch

This project is continuously deployed to cloud.gov with every commit to the master branch. Right now, you can use the application at https://crime-data-explorer-master.fr.cloud.gov.

Stable

Tagged releases are deployed to https://crime-data-explorer.fr.cloud.gov.

Staging

A third, and less formal, environment is available at https://crime-data-explorer-staging.fr.cloud.gov. This is for ad-hoc usage and testing.

Use cf push -f manifest/staging.yml to deploy. Remember that cf pushes from your local file structure and won't build the app on its own, so make sure you run npm run build before pushing.

Release process

This app follows semver and has tagged releases by version number. You can see all notable changes in CHANGELOG.md.

We use the following criteria to determine the proper next version number. A major version change is appropriate when the URL structure has changed (breaking any existing URLs) or when there is a major removal of content. A minor version change is appropriate when the changes include more than bug fixes but not breaking changes. A patch version is appropriate when only bugs or security issues are addressed.

Manual verification

Though unit test coverage is decent (check with npm run coverage, as of cdb2340 it was about 77% of all statements), we run through a few basic user scenarios before tagging a release to check the application. We are working on getting the automated browser tests to replicate this exact process.

1. Load homepage from master branch. Can be local or https://crime-data-explorer-master.fr.cloud.gov
2. Select "Explorer" from navigation
3. Ensure that a trend chart renders to show "Violent Crime rate in United States"
4. Select "Alabama" as the location in the left hand side menu
5. Select "Robbery" as the crime in the left hand side menu
6. Ensure that the URL is now /explorer/state/alabama/robbery
7. Ensure that a trend chart renders to show "Robbery rate in Alabama, 2004–2014"
8. Scroll down and ensure donut charts, histograms, and tables render to show "Robbery incident details in Alabama, 2004–2014"
9. Scroll down and ensure there is a section called "About the data"
10. Select "Downloads & Documentation" from the navigation at the top of the page or the footer at the bottom
11. Select "Alabama" as the "Location" and "2000" as the "Year". Click download and ensure that a .zip file is downloaded
12. Click the "Download CSV" link in the "Hate Crime" dataset section under the heading "Additional Datasets" and ensure a file called hate_crime.csv is downloaded

Tagging a release

1. Compile the notable changes into the CHANGELOG.md. You can use the /compare/:lastVersion...master endpoint on Github. For example, this /compare link was used to determine the changes in v1.1.0
2. Determine if the version should be increased by a major, minor, or patch version
3. Adjust the version number in package.json accordingly
4. Submit a pull request without tagging the commit
5. Once the pull request is merged, tag the merge commit (on master) as vX.Y.Z where X, Y, and Z reflect the same version number as the now merged change for package.json
6. Push the tag to Github with git push origin vX.Y.Z

Browser support

We explicitly support Chrome, Safari, IE 10+, Firefox, and MS Edge.