API Specification·Web Service Reference

SpotCrime API Specification

The complete reference for the SpotCrime crime-data web service: endpoints, parameters, crime types, and JSON response shapes. Two simple GET endpoints return real-time, geocoded incident data for any point in the United States.

Base URL https://api.spotcrime.comFormat JSON / JSONPLast updated October 21, 2023

Get an API Key

Endpoints

Crime search · Crime detail

Method

GET

Simple HTTPS requests

Response

JSON

Optional JSONP callback

Auth

API key

Per-customer · static-IP bound

Data window

90 days

Rolling · 6mo on Pro annual

Getting started

Authentication

Every request is authenticated with the API key SpotCrime issues to you, passed as the key query parameter. Keys are tied to a single customer — keep them secret, never embed them in client-side code, and rotate immediately if one is exposed.

Static IP required (all plans)

Every API key is bound to the static IP address(es) you register with SpotCrime. Requests from any other IP are rejected. You must provide at least one static IP before your key is issued; you can register more than one and update them by contacting us. This applies to every plan.

Need a key?

Request access at spotcrime.io/request-access. Usage terms are governed by the API License Agreement.

Important

Data Coverage & Availability

The SpotCrime API serves recent incident data. The coverage window is the most important thing to understand before you build.

Standard API

90 days

Both endpoints return incidents from a rolling 90-day window. Included on the Developer and Pro (monthly) plans.

Pro annual

6 months

The annual Pro plan extends the lookback to a 6-month historical window.

Enterprise · archives

AWS S3

Data beyond 6 months, deeper datasets, and bulk historical archives are delivered separately in all standard formats via AWS S3.

What this means for your queries

The sinceparameter narrows the window but cannot reach beyond your plan’s coverage: requests for dates older than the window return no results rather than an error. If you need a longer lookback (6 months on Pro annual) or a bulk archive, talk to us about Enterprise.

Endpoint 1

General Crime Search

Returns a JSON list of crimes around a specific point, subject to the parameters below. This is the core endpoint behind SpotCrime’s public maps and partner integrations.

GET/crimes.json

Parameters

Parameter	Required	Permitted values	Description
`lat` number	Required	Any valid floating-point latitude	Latitude of the center point of the search.
`lon` number	Required	Any valid floating-point longitude	Longitude of the center point of the search.
`radius` number	Required	Any valid floating-point value	Search radius around the lat/lon, in decimal degrees. Larger values cover more area and take longer to return. We recommend a radius of 0.01 or smaller. (1 mile ≈ 0.01448.)
`key` string	Required	Your SpotCrime API key	The API key issued to you by SpotCrime. Treat it as a secret.
`since` date	Optional Highly recommended	YYYY-MM-DD	Only crimes that occurred after this date are returned. Filters within the rolling 90-day window — dates older than the window return no results. Optional, but specifying a value is strongly recommended for performance and relevance.
`max_records` integer	Optional Default: 50	1–500 (inclusive)	Maximum number of crimes to return. Capped at 500.
`sort_by` string	Optional Default: date	date or distance	Sort the JSON results by report date or by distance from the center point.
`sort_order` string	Optional Default: DESC	ASC or DESC	Sort the JSON results in ascending or descending order.
`types` string (CSV)	Optional Default: all types	Comma-delimited crime types	Comma-delimited list of crime types to include in the results.
`callback` string	Optional	Any valid JS function name	If specified, the JSON payload is wrapped in a JavaScript function with this name (JSONP).

Crime types

Pass any combination of these values to types as a comma-delimited list. Omit the parameter to return every type.

arrestarsonassaultburglaryrobberyshootingtheftvandalismother

Sample requests

All crimes within a 0.01° radius, sorted by location, wrapped in a JSONP callback named jsonp1:

https://api.spotcrime.com/crimes.json?lat=39.280899&lon=-76.581888&radius=0.01&callback=jsonp1&key=YOUR_KEY

Up to 10 assaults and burglaries within a 0.05° radius, newest first:

https://api.spotcrime.com/crimes.json?lat=39.280899&lon=-76.581888&radius=0.05&max_records=10&types=assault,burglary&key=YOUR_KEY

Sample response

Formatted for readability — production output omits whitespace.

{
  "crimes": [
    {
      "type": "Assault",
      "address": "8XX N. CAROLINE STREET",
      "lat": 39.2993153,
      "lon": -76.5976891,
      "cdid": 23923102,
      "date": "10/17/11 09:00 PM",
      "link": "https://spotcrime.com/crime/23923102-88a90eee2890388cf8c679b4519c4619"
    }
  ]
}

Endpoint 2

Specific Crime Detail

Returns the full record for a single incident, including its narrative description. Look up a crime by the cdid returned in any search result.

GET/crimes/{cdid}.json

Parameters

Parameter	Required	Permitted values	Description
`cdid` integer	Required	A crime detail ID (cdid)	The unique crime ID, taken from the cdid field of a search result. Provided in the request path, not the query string.
`key` string	Required	Your SpotCrime API key	The API key issued to you by SpotCrime.

Sample request

https://api.spotcrime.com/crimes/23923102.json?key=YOUR_KEY

Sample response

Formatted for readability — production output omits whitespace.

{
  "type": "Assault",
  "address": "8XX N. CAROLINE STREET",
  "lat": 39.2993153,
  "lon": -76.5976891,
  "cdid": 23923102,
  "date": "10/17/11 09:00 PM",
  "link": "https://spotcrime.com/crime/23923102-88a90eee2890388cf8c679b4519c4619",
  "description": "Reported assault. Officers responded to the location and a report was filed. See the linked incident for the agency's public narrative."
}

Reference

Response Fields

Every incident object can contain the following fields. The description field is returned only by the crime detail endpoint.

Field	Type	Description
`type`	string	Crime category, e.g. "Assault", "Robbery", "Theft".
`address`	string	Block-level street address of the incident.
`lat`	number	Latitude of the incident.
`lon`	number	Longitude of the incident.
`cdid`	integer	Unique crime detail ID. Pass it to the detail endpoint.
`link`	string (URL)	Permalink to the incident on spotcrime.com.
`date`	string	Local report date & time, formatted MM/DD/YY HH:MM AM/PM.
`description`	string	Narrative description of the incident. Returned by the detail endpoint only.

Guidance

Notes & Best Practices

Keep the radius small

Larger radii scan more area and respond more slowly. Stay at 0.01° or below where possible; 1 mile is roughly 0.01448°.

Always set since

It’s optional but strongly recommended. Bounding results to a recent date keeps responses fast and relevant.

Page with max_records

Defaults to 50, caps at 500. Combine with sort_by and sort_order to control which records you receive.

Use callback for JSONP

Supplying callback wraps the JSON in a JavaScript function for legacy cross-origin browser use. Prefer a server-side request with CORS otherwise.

Ready to build?

Request an API key and start pulling real-time crime data across 22,000+ U.S. cities. Looking for the interactive developer guide with code samples? See the full documentation.

Get an API Key Full API Documentation View Pricing