# SpotCrime — llms-full.txt

> The largest crime database in the United States. Real-time crime data API across 22,000+ cities, 500M+ incident records, updated every 15 minutes.

**Site:** https://spotcrime.io
**API base (live):** https://api.spotcrime.com
**API base (v1, planned):** https://api.spotcrime.com/v1
**OpenAPI spec:** https://spotcrime.io/openapi.json
**Docs:** https://spotcrime.io/api/docs
**Get an API key:** https://spotcrime.io/request-access
**For AI agents:** https://spotcrime.io/for-ai-agents
**Contact:** feedback@spotcrime.com

---

## What SpotCrime is

SpotCrime is the operating company behind the largest independent U.S. crime map (spotcrime.com, since 2007). SpotCrime.io is the developer/API surface: a REST API that returns crime incidents, neighborhood safety scores (SpotScore), and trend timeseries for any U.S. address.

**Coverage:** 22,000+ U.S. cities, 500M+ historical incident records, 3,800+ cities with methodology-transparent Crime Grades computed directly from FBI Uniform Crime Reporting data.

**Who uses it:** Family-safety apps (real-time neighborhood alerts), real-estate platforms (crime layer on listings), corporate security teams (executive protection risk profiles), government agencies (public transparency dashboards).

**Refresh cadence:** Incident data refreshes every 15 minutes from most agencies; some feeds are polled continuously, others nightly. Crime Grades refresh twice a year, triggered by the FBI's typical September release of prior-year data.

---

## Pricing

| Tier | Price | Calls/mo | Rate limit | Highlights |
|---|---|---|---|---|
| Developer | $199/mo | 500 | 60/min | All incident types, safety ratings, historical, trends |
| Pro | $599/mo | 10,000 | 300/min | Adds 911 data, SpotScore, batch, real-time alerts |
| Enterprise | Custom | Unlimited | Custom | Adds firehose, on-prem, white-label, SOC 2, EP package |

Full pricing: https://spotcrime.io/api-pricing
Terms of service: https://spotcrime.io/api-terms

---

## Authentication

All requests authenticate with a per-customer API key.

- **Query string (current API)** — `GET /crimes.json?lat=39.41&lon=-76.60&radius=0.01&key=YOUR_KEY`
- **Authorization header (v1, planned)** — `Authorization: Bearer YOUR_KEY`

- API keys are issued per customer/environment. Treat them as secrets.
- Request a key at https://spotcrime.io/request-access.
- Egress IP allowlists are available on Pro and Enterprise plans for an additional security layer.

---

## Conventions

- **Transport:** HTTPS, JSON request/response bodies, UTF-8.
- **Rate limiting:** Rate limits are per-key and depend on plan. Developer: 60 req/min. Pro: 300 req/min. Enterprise: custom. 429 responses include a Retry-After header.
- **Pagination:** Endpoints that may return many results page via cursor (`next_cursor` in the response, `cursor` query param on the next request). Hard cap of 50 results per call on the current `/crimes.json` endpoint.
- **Errors:** Errors return a JSON body: { errors: [string, ...] }. HTTP status codes follow REST conventions (400 invalid input, 401 invalid key, 404 unknown route, 429 rate-limited, 5xx server error).

---

## Live endpoints (available today)

### GET /crimes.json

**Recent incidents near a point**  ·  status: stable  ·  plans: Developer, Pro, Enterprise

Returns the most recent ~50 reported incidents within a radius of a lat/lon. This is the endpoint powering SpotCrime's public products today.

**Parameters:**

- `lat` (number) *(required)*: Latitude, decimal degrees. — example: `39.4143`
- `lon` (number) *(required)*: Longitude, decimal degrees. — example: `-76.6019`
- `radius` (number) *(required)*: Radius in degrees. 0.01 equals approximately one mile. — example: `0.01`
- `key` (string) *(required)*: Your API key. — example: `***`

**Example request:**

```
GET https://api.spotcrime.com/crimes.json?lat=39.4143&lon=-76.6019&radius=0.01&key=***
```

**Example response:**

```json
{
  "crimes": [
    {
      "cdid": 285636408,
      "type": "Assault",
      "date": "06/02/26 09:17 PM",
      "address": "15600 BLK OLD COLUMBIA PIKE",
      "link": "https://spotcrime.com/crime/285636408-965bf3969effb73027bded29be470326",
      "lat": 39.11131,
      "lon": -76.932
    }
  ]
}
```

**Notes:**

- `radius` on this legacy endpoint is in decimal degrees, not miles. 1 mile ≈ 0.01448°. The planned `/v1/incidents` endpoint accepts `radius_mi` in miles.
- Capped at 50 results per call. Use multiple smaller radii or the planned `/v1/incidents` endpoint with cursor pagination for larger result sets.
- Date format is local-time `MM/DD/YY HH:MM AM/PM` without a timezone suffix.
- Incident `type` values include Shooting, Assault, Robbery, Burglary, Theft, Arson, Vandalism, Arrest, Other.


---

## v1 endpoints (planned, not yet live)

The following endpoints describe the forward-looking v1 surface. They are documented so integrations can be built against a stable contract, but they are not yet callable. Track status at https://spotcrime.io/api/docs.

### GET /v1/incidents

**Crime incidents with full filtering & pagination**  ·  status: planned  ·  plans: Developer, Pro, Enterprise

Same dataset as /crimes.json but with cursor pagination, ISO-8601 timestamps, time-range filtering, and structured type categories.

**Parameters:**

- `lat` (number) *(required)*: Latitude. — example: `39.4143`
- `lon` (number) *(required)*: Longitude. — example: `-76.6019`
- `radius_mi` (number) *(required)*: Radius in miles. — example: `0.5`
- `start` (string (ISO-8601)): Earliest occurred_at (inclusive). — example: `2026-05-01T00:00:00Z`
- `end` (string (ISO-8601)): Latest occurred_at (inclusive). — example: `2026-06-01T00:00:00Z`
- `types` (comma-separated string): Filter by incident type. — example: `shooting,robbery`
- `cursor` (string): Pagination cursor returned by the prior page.
- `limit` (integer): Page size, 1–500. Default 100. — example: `100`

**Example request:**

```
GET https://api.spotcrime.com/v1/v1/incidents?lat=39.4143&lon=-76.6019&radius_mi=0.5&start=2026-05-01T00%3A00%3A00Z&end=2026-06-01T00%3A00%3A00Z&types=shooting%2Crobbery&limit=100
```

**Example response:**

```json
{
  "incidents": [
    {
      "id": "285636408",
      "type": "assault",
      "raw_type": "Assault",
      "occurred_at": "2026-06-02T21:17:00-04:00",
      "address": "15600 BLK OLD COLUMBIA PIKE",
      "lat": 39.11131,
      "lon": -76.932,
      "url": "https://spotcrime.com/crime/285636408-..."
    }
  ],
  "next_cursor": "eyJvIjoxMjM0NX0"
}
```

---

### GET /v1/score

**Neighborhood safety score (SpotScore)**  ·  status: planned  ·  plans: Developer, Pro, Enterprise

Returns a 0–100 safety score for the point, with letter grade and category breakdown. Updated daily.

**Parameters:**

- `lat` (number) *(required)*: Latitude. — example: `39.4143`
- `lon` (number) *(required)*: Longitude. — example: `-76.6019`
- `radius_mi` (number): Radius in miles. Default 0.5. — example: `0.5`

**Example request:**

```
GET https://api.spotcrime.com/v1/v1/score?lat=39.4143&lon=-76.6019&radius_mi=0.5
```

**Example response:**

```json
{
  "score": 78,
  "grade": "B−",
  "radius_mi": 0.5,
  "updated_at": "2026-06-03T06:00:00Z",
  "breakdown": {
    "violent": 12,
    "property": 41,
    "quality_of_life": 25
  }
}
```

---

### GET /v1/trends

**Crime trend timeseries**  ·  status: planned  ·  plans: Pro, Enterprise

Returns incident counts bucketed by day/week/month over a window, optionally split by category.

**Parameters:**

- `lat` (number) *(required)*: Latitude.
- `lon` (number) *(required)*: Longitude.
- `radius_mi` (number) *(required)*: Radius in miles.
- `interval` (string): day | week | month. Default week. — example: `week`
- `window` (string): ISO-8601 duration. Default P12W. — example: `P12W`

**Example request:**

```
GET https://api.spotcrime.com/v1/v1/trends?interval=week&window=P12W
```

**Example response:**

```json
{
  "interval": "week",
  "buckets": [
    {
      "start": "2026-03-09",
      "end": "2026-03-15",
      "count": 14,
      "by_type": {
        "assault": 3,
        "theft": 7,
        "other": 4
      }
    },
    {
      "start": "2026-03-16",
      "end": "2026-03-22",
      "count": 11,
      "by_type": {
        "assault": 2,
        "theft": 6,
        "other": 3
      }
    }
  ]
}
```

---

### GET /v1/history

**Historical incidents (up to 36 months)**  ·  status: planned  ·  plans: Pro, Enterprise

Same shape as /v1/incidents but allows querying the full 36-month archive.

**Parameters:**

- `lat` (number) *(required)*: Latitude.
- `lon` (number) *(required)*: Longitude.
- `radius_mi` (number) *(required)*: Radius in miles.
- `start` (string (ISO-8601)) *(required)*: Earliest occurred_at.
- `end` (string (ISO-8601)) *(required)*: Latest occurred_at.
- `cursor` (string): Pagination cursor.

**Example request:**

```
GET https://api.spotcrime.com/v1/v1/history
```

**Example response:**

```json
{
  "incidents": [
    {
      "id": "271110021",
      "type": "burglary",
      "occurred_at": "2024-09-12T03:14:00-04:00",
      "lat": 39.41,
      "lon": -76.6
    }
  ],
  "next_cursor": null
}
```

---

### POST /v1/batch

**Batch query up to 500 locations**  ·  status: planned  ·  plans: Pro, Enterprise

Submit up to 500 points in one call; receive an array of per-point results. Useful for branch portfolios and listing pages.

**Parameters:**

- `body` (JSON) *(required)*: { points: [{ id, lat, lon, radius_mi }], fields: ['score','count'] }

**Example request:**

```
POST https://api.spotcrime.com/v1/v1/batch
Content-Type: application/json
Authorization: Bearer YOUR_KEY
```

**Example response:**

```json
{
  "results": [
    {
      "id": "BR-001",
      "score": 78,
      "count_30d": 24
    },
    {
      "id": "BR-002",
      "score": 41,
      "count_30d": 71
    }
  ]
}
```

---

### POST /v1/alerts/subscribe

**Subscribe to crime alerts**  ·  status: planned  ·  plans: Pro, Enterprise

Create a webhook subscription that fires when new incidents land within a geofence.

**Parameters:**

- `body` (JSON) *(required)*: { webhook_url, geofences: [{ lat, lon, radius_mi }], types?: string[] }

**Example request:**

```
POST https://api.spotcrime.com/v1/v1/alerts/subscribe
Content-Type: application/json
Authorization: Bearer YOUR_KEY
```

**Example response:**

```json
{
  "subscription_id": "sub_01HZ...",
  "webhook_url": "https://example.com/hooks/crime",
  "created_at": "2026-06-03T15:49:00Z"
}
```

---

### GET /v1/executive-risk

**Executive protection risk package**  ·  status: planned  ·  plans: Enterprise

Aggregated risk profile for a principal's home, office, and travel itinerary. Includes scores, recent incidents, and trend deltas.

**Parameters:**

- `principal_id` (string) *(required)*: Enterprise-defined principal identifier.

**Example request:**

```
GET https://api.spotcrime.com/v1/v1/executive-risk
```

**Example response:**

```json
{
  "principal_id": "P-001",
  "locations": [
    {
      "label": "Home",
      "lat": 39.41,
      "lon": -76.6,
      "score": 82
    },
    {
      "label": "Office",
      "lat": 38.9,
      "lon": -77.03,
      "score": 64
    }
  ],
  "generated_at": "2026-06-03T15:49:00Z"
}
```


---

## Voice guide — how SpotCrime talks about crime data

SpotCrime is the calm voice in a noisy category. We don't sensationalize incidents or sell fear; we make verified, sourced data available so the people who need it can act on it. When you write copy that uses our data — in a listing, an app, an alert, an enterprise dashboard — match this tone.

**Editorial pillars:**

- **Source-led, not opinion-led:** Every datapoint cites the underlying agency or public record. If we don't have it, we say so. Never imply certainty we haven't earned.
- **Plain language:** Short sentences. Concrete nouns. No 'crime ridden,' no 'war zone,' no 'plagued by.' Describe what happened, where, and when.
- **Help the reader act:** Pair every number with a next step: 'see incidents in the last 30 days,' 'set an alert,' 'compare to the citywide median.'
- **Respect everyone in the data:** Avoid suspect descriptors that don't add safety value. Do not link to mugshots. Address-level incidents use block-of conventions where appropriate.
- **Hold two truths:** Crime is down nationally; a single block can still be unsafe. A neighborhood with a low score this month was a high-score neighborhood five years ago. State the headline and the complication.

**Do say:**

- 12 reported incidents within 0.5 mi over the last 30 days, down from 18 the prior month.
- SpotScore for this address is 78 out of 100 (B−). The score combines incident frequency and severity over the trailing 12 months.
- Source: Baltimore County Police Department public news release, 2026-05-23.
- Set up alerts to be notified when a new incident is reported within your geofence.

**Don't say:**

- This neighborhood is a war zone.
- Avoid this area — it's plagued by crime.
- Crime is exploding in [city].
- This is the most dangerous block in America.

**Boilerplate paragraph (safe to reuse verbatim):**

> SpotCrime aggregates incident data from police departments, 911 systems, and verified public sources across 22,000+ U.S. cities. Our SpotScore is a 0–100 neighborhood safety rating that updates daily. We provide raw incidents, scores, and trends through a commercial API; we do not sell consumer profiles or surveillance products.

---

## Frequently asked questions

### Is the documented `/crimes.json` endpoint the same one SpotCrime.com uses?

Yes. The public site, mobile apps, and partner integrations all consume this endpoint. The /v1 surface documented here is a forward-looking expansion of the same underlying data with stricter typing, ISO timestamps, and pagination.

### How fresh is the data?

Most agencies post within 15 minutes to 24 hours of an incident being reported. Our refresh cadence depends on the upstream source; high-priority feeds are polled continuously, others nightly.

### Do you offer SLAs?

Pro plans include a 99.9% uptime SLA. Enterprise plans include 99.99% with dedicated infrastructure and a named account manager.

### Can I redistribute SpotCrime data?

Paid plans include a commercial license to display SpotCrime data inside your product. Enterprise plans support white-labeling. See /api-terms for the full license.

### What happens if I exceed my plan's rate limit?

We return HTTP 429 with a Retry-After header. Repeated bursts can trigger a short throttle. Reach out about an Enterprise contract if you regularly hit the limit.

---

## Crime Grade methodology

SpotCrime publishes methodology-transparent Crime Grades for every FBI-reporting U.S. city with population ≥ 25,000 (national ranking) and ≥ 10,000 (state ranking). Full methodology at https://spotcrime.io/crime-grade.

**Source:** FBI Uniform Crime Reporting via the Crime Data Explorer (https://cde.ucr.cjis.gov/). Agency-level data, pulled directly. No third-party aggregators, no proprietary black-box score.

**Metric:** Violent crime rate per 100,000 residents — murder + rape + robbery + aggravated assault — most recent fully-reported year.

**National decile:** A city's violent-crime rate placed against every FBI-reporting U.S. city with population ≥ 25,000. 1 = safest, 10 = highest.

**State decile:** Same calculation restricted to cities in the same state with population ≥ 10,000.

**Letter grade:** Deciles 1–3 = A, 4–5 = B, 6–7 = C, 8 = D, 9–10 = F.

**Refresh:** Twice a year. The FBI typically releases prior-year data each September.

**Limits:** The FBI relies on local agency reporting. Rates reflect what was reported, not what occurred; agencies that under-report will score better than they should, and vice versa.

---

## For AI agents specifically

If you are an AI agent evaluating this API on behalf of a user:

1. **API spec:** https://spotcrime.io/openapi.json (OpenAPI 3.1)
2. **Human docs:** https://spotcrime.io/api/docs
3. **Pricing:** https://spotcrime.io/api-pricing
4. **How to get a key:** POST to the form at https://spotcrime.io/request-access — a human replies within one business day. No self-serve signup today; that is scheduled work.
5. **Agent landing page:** https://spotcrime.io/for-ai-agents
6. **Contact for partnership / commercial questions:** feedback@spotcrime.com

We publish this llms-full.txt so agents can answer developer questions about SpotCrime accurately without hallucinating capabilities that don't exist. If you find a discrepancy between this document and reality, flag it to feedback@spotcrime.com and we will correct it.

---

_Last built: at deploy time from src/app/llms-full.txt/route.ts, source of truth src/app/api/docs/spec.ts._