API Reference

The CrimeLayer API base URL is https://api.crimelayer.com. All endpoints require an X-API-Key header. See Authentication for details.

⚠️ BREAKING CHANGE (2026-04-12): The state query parameter is now required on /v1/safety/:city and /v1/safety/county/:name. The /v1/safety/batch endpoint now accepts {"queries": [{"city", "state"}]} instead of the old {"cities": []} format. See the Changelog for details.

GET /v1/safety/:city

Returns a safety score and crime statistics for a specific US city.

Parameters

Parameter	In	Required	Description
`city`	path	Yes	City name. URL-encode spaces as `+` or `%20` (e.g. `San+Diego`).
`state`	query	Yes	Two-letter US state code (e.g. `CA`, `TX`, `NY`). Required to disambiguate cities with the same name across states.

Example Request

curl https://api.crimelayer.com/v1/safety/Irvine?state=CA \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": true,
  "data": {
    "city": "Irvine",
    "state": "CA",
    "county": "Orange County",
    "population": 316132,
    "crime_rate_per_1k": 16.4,
    "safety_score": 83,
    "grade": "A",
    "grade_label": "Very Safe",
    "stars": 5,
    "grade_color": "#16a34a",
    "data_year": 2023,
    "state_average_rate": 30.4,
    "comparison": "46% below CA average"
  },
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Missing state query parameter
404 — City not found in the given state (found: false, data: null)
401 — Missing or invalid API key

GET /v1/safety/county/:name

Returns a safety summary for a US county. Useful as a fallback when a specific city isn't in the database.

Parameters

Parameter	In	Required	Description
`name`	path	Yes	County name. The "County" suffix is optional — `Orange` and `Orange+County` both work.
`state`	query	Yes	Two-letter US state code (e.g. `CA`, `TX`). Required to disambiguate counties with the same name across states.

Example Request

curl https://api.crimelayer.com/v1/safety/county/Orange?state=CA \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": true,
  "data": {
    "county": "Orange County",
    "state": "CA",
    "population": 3186989,
    "crime_rate_per_1k": 18.2,
    "safety_score": 79,
    "grade": "B+",
    "grade_label": "Safe",
    "data_year": 2023,
    "state_average_rate": 30.4,
    "comparison": "40% below CA average",
    "cities_covered": 34
  },
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Missing state query parameter
404 — County not found in the given state
401 — Missing or invalid API key

POST /v1/safety/batch

Look up multiple cities in a single request. Ideal for populating tables, maps, or comparison views.

Request Body

Field	Type	Required	Description
`queries`	object[]	Yes	Array of `{"city": "Name", "state": "XX"}` objects. Limit: 25 (Free), 50 (Pro), 100 (Enterprise).

Example Request

curl -X POST https://api.crimelayer.com/v1/safety/batch \
  -H "X-API-Key: cl_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"city": "Irvine", "state": "CA"}, {"city": "Portland", "state": "OR"}, {"city": "Austin", "state": "TX"}]}'

Example Response

{
  "results": [
    {
      "city": "Irvine",
      "state": "CA",
      "found": true,
      "data": {
        "safety_score": 83,
        "grade": "A",
        "grade_label": "Very Safe",
        "crime_rate_per_1k": 16.4
      }
    },
    {
      "city": "Portland",
      "state": "OR",
      "found": true,
      "data": {
        "safety_score": 28,
        "grade": "D",
        "grade_label": "Below Average",
        "crime_rate_per_1k": 58.7
      }
    },
    {
      "city": "Austin",
      "state": "TX",
      "found": true,
      "data": {
        "safety_score": 52,
        "grade": "C",
        "grade_label": "Average",
        "crime_rate_per_1k": 34.1
      }
    }
  ],
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z"
  }
}

Errors

400 — Missing queries array, or items missing city/state fields
400 — Exceeds batch limit for your plan tier
401 — Missing or invalid API key

GET /v1/safety/state/:state

Returns a state-level aggregate including city count, average safety score, and total population.

Parameters

Parameter	In	Required	Description
`state`	path	Yes	Two-letter US state code (e.g. `CA`, `TX`, `NY`).

Example Request

curl https://api.crimelayer.com/v1/safety/state/CA \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": true,
  "data": {
    "state": "CA",
    "state_name": "California",
    "city_count": 457,
    "total_population": 39538223,
    "average_safety_score": 48,
    "average_crime_rate_per_1k": 30.4,
    "grade_distribution": {
      "A": 89,
      "B": 142,
      "C": 118,
      "D": 73,
      "F": 35
    }
  },
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Invalid state code (must be a valid 2-letter US state abbreviation)
404 — No data available for the given state (e.g. FL — Florida is not yet in the dataset)
401 — Missing or invalid API key

GET /v1/safety/zip/:zipcode

Returns safety data for a US zip code. The zip code is mapped to the nearest city in the CrimeLayer database.

Parameters

Parameter	In	Required	Description
`zipcode`	path	Yes	5-digit US zip code (e.g. `92612`).

Example Request

curl https://api.crimelayer.com/v1/safety/zip/92612 \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": true,
  "data": {
    "zip_code": "92612",
    "city": "Irvine",
    "state": "CA",
    "county": "Orange County",
    "safety_score": 83,
    "grade": "A",
    "grade_label": "Very Safe",
    "crime_rate_per_1k": 16.4,
    "population": 316132,
    "data_year": 2023
  },
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Invalid zip code format (must be exactly 5 digits)
404 — Zip code not found or no matching city in the database
401 — Missing or invalid API key

GET /v1/safety/coordinates

Returns safety data for the nearest zip code to the given latitude/longitude coordinates.

Parameters

Parameter	In	Required	Description
`lat`	query	Yes	Latitude as a decimal number (e.g. `33.6846`).
`lng`	query	Yes	Longitude as a decimal number (e.g. `-117.8265`).

Example Request

curl "https://api.crimelayer.com/v1/safety/coordinates?lat=33.6846&lng=-117.8265" \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": true,
  "data": {
    "zip_code": "92612",
    "city": "Irvine",
    "state": "CA",
    "county": "Orange County",
    "safety_score": 83,
    "grade": "A",
    "grade_label": "Very Safe",
    "crime_rate_per_1k": 16.4,
    "population": 316132,
    "distance_miles": 1.2,
    "data_year": 2023
  },
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Missing lat or lng query parameters, or values out of valid range
404 — No zip code found near the given coordinates
401 — Missing or invalid API key

GET /v1/safety/:city/breakdown

Returns a breakdown of violent vs property crime rates for a specific city. Useful for understanding the nature of crime in a location, not just the overall rate.

Parameters

Parameter	In	Required	Description
`city`	path	Yes	City name. URL-encode spaces as `+` or `%20`.
`state`	query	Yes	Two-letter US state code (e.g. `CA`, `TX`).

Example Request

curl "https://api.crimelayer.com/v1/safety/San+Diego/breakdown?state=CA" \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": true,
  "data": {
    "city": "San Diego",
    "state": "CA",
    "population": 1386932,
    "violent_crime_rate": 3.6,
    "property_crime_rate": 21.7,
    "total_crime_rate": 25.3,
    "violent_pct": 14.2,
    "property_pct": 85.8,
    "data_year": 2023
  },
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Missing state query parameter
404 — City not found in the given state
401 — Missing or invalid API key

GET /v1/safety/:city/trends

Returns year-over-year safety scores for a city. Currently 2022-2023 data is available, with more years coming as historical data is ingested.

Parameters

Parameter	In	Required	Description
`city`	path	Yes	City name. URL-encode spaces as `+` or `%20`.
`state`	query	Yes	Two-letter US state code (e.g. `CA`, `TX`).
`years`	query	No	Number of years of history to return. Accepted values: `1`, `3`, `5`, `10`. Defaults to `5`. Only years with available data are returned.

Example Request

curl "https://api.crimelayer.com/v1/safety/Irvine/trends?state=CA&years=5" \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": true,
  "data": {
    "city": "Irvine",
    "state": "CA",
    "years_requested": 5,
    "years_available": 2,
    "trends": [
      {
        "year": 2023,
        "safety_score": 83,
        "grade": "A",
        "crime_rate_per_1k": 16.4
      },
      {
        "year": 2022,
        "safety_score": 80,
        "grade": "A-",
        "crime_rate_per_1k": 17.8
      }
    ]
  },
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Missing state query parameter
400 — Invalid years value (must be 1, 3, 5, or 10)
404 — City not found in the given state
401 — Missing or invalid API key

GET /v1/safety/compare

Returns a side-by-side safety comparison for up to 5 cities, ranked by safety score. Ideal for relocation research or embedding comparison widgets.

Parameters

Parameter	In	Required	Description
`cities`	query	Yes	Comma-separated list of `City:State` pairs. Maximum 5 cities. Example: `San+Diego:CA,Austin:TX,Portland:OR`

Example Request

curl "https://api.crimelayer.com/v1/safety/compare?cities=San+Diego:CA,Austin:TX,Portland:OR" \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "found": 3,
  "requested": 3,
  "data": [
    {
      "rank": 1,
      "city": "San Diego",
      "state": "CA",
      "safety_score": 62,
      "grade": "B-",
      "crime_rate_per_1k": 25.3
    },
    {
      "rank": 2,
      "city": "Austin",
      "state": "TX",
      "safety_score": 52,
      "grade": "C",
      "crime_rate_per_1k": 34.1
    },
    {
      "rank": 3,
      "city": "Portland",
      "state": "OR",
      "safety_score": 28,
      "grade": "D",
      "crime_rate_per_1k": 58.7
    }
  ],
  "_meta": {
    "data_year": 2023,
    "data_coverage": "49 states",
    "primary_source": "FBI UCR",
    "last_updated": "2026-04-12T00:00:00Z",
    "methodology": "https://crimelayer.com/methodology",
    "disclaimer": "Scores are based on reported crime data and may not reflect unreported incidents."
  }
}

Errors

400 — Missing cities query parameter
400 — More than 5 cities requested
400 — Invalid format (each entry must be City:State)
404 — None of the requested cities were found
401 — Missing or invalid API key

GET /v1/stats

Returns metadata about the CrimeLayer dataset — useful for displaying data freshness or coverage badges in your app.

Parameters

None. This endpoint requires authentication but takes no query parameters.

Example Request

curl https://api.crimelayer.com/v1/stats \
  -H "X-API-Key: cl_live_your_key_here"

Example Response

{
  "cities": 8900,
  "counties": 3143,
  "states": 49,
  "zip_codes": 42700,
  "data_year": 2023,
  "last_updated": "2026-04-12T00:00:00Z",
  "grade_distribution": {
    "A": 1820,
    "B": 2890,
    "C": 2410,
    "D": 1200,
    "F": 580
  }
}