Skip to content

Latest commit

 

History

History
executable file
·
101 lines (77 loc) · 3.77 KB

api_support_notes.md

File metadata and controls

executable file
·
101 lines (77 loc) · 3.77 KB

Available fields for API

The Crime Data API is what powers the CDE website (whose code is at crime-data-explorer. All API requests require an API key which can be provided to you securely by a FBI CDE team member.

All API endpoints are documented in Swagger, and interactive documentation can be found at https://crime-data-api.fr.cloud.gov/swagger-ui/

Note that this documentation is still not feature-complete. Many fields are missing descriptions and the documentation will focus primarily on what the frontend developers on the FBI project need before making the documentation more accessible. This document is a supplement to the Swagger documentation with some general notes about API usage.

/incidents/

This is the endpoint used to query specific records from NIBRS. It should not be used to aggregate NIBRS statistics.

You can filter by any field in the results of an /incidents/ query by appending values to the query string in the API call. The /meta/incidents API endpoint returns a list of fields that can be filtered on. In some cases, fields might be codes within the FBI database (ie, state_id or offense_type_code). To get a list of those possible values, look for one of the endpoints listed in the /codes/ API endpoint.

/incidents/count

This is the endpoint used to query specific records from SRS aka "Return A" records. It should not be used to aggregate NIBRS statistics.

You can filter by any field in the results of an /incidents/count query by appending values to the query string in the API call. The /meta/incidents/count API endpoint returns a list of fields that can be filtered on. In some cases, fields might be codes within the FBI database (ie, state_id or offense_type_code). To get a list of those possible values, look for one of the endpoints listed in the /codes/ API endpoint.

You can also filter by any field in agencies or its child tables (location, etc.); the handiest place to see these fields is in the results of an /incidents/ query.

Including by=field1_name,field2_name,field3_name in the parameters will group the results by, and show, those field names.

Other Endpoints

The /incidents and /incidents/count endpoints are essentially broad by design, so that they could be used to explore future directions for the front-end interface. This does not make them especially performant however, and as the CDE frontend is built, we will develop more specific and efficient endpoints for elements on the CDE pages. Your best bet is to refer to the Swagger UI for the most up-to-date listing on all the methods.

General filtering rules

The API supports filtering for

  • equality (fieldname=val)
  • inequality (fieldname!=val)
  • comparison (fieldname>=val, fieldname>=val, fieldname<val, fieldname<=val)

Filters are case-insensitive.

The API does not yet support joining filters with OR or partial-string matches. Your input in how to prioritize those is valued.

Speed

Filtered queries will be slow unless an index exists on that table. Currently existing indexes are in dba/manual_sql/indexes.sql. They are easy to add - disk space is the only expense - so please request whatever indexes the app requires!

Pagination

App supports page and per_page arguments. Note that for large queries, the total results returned will be a rough estimate for performance reasons. This means that if we were to paginate over all records, the total nimber of pages might be less or more than the reported number of pages. Queries that are estimated to return less than a 1000 records are then precisely counted so that will not be an issue for them.