Exact counts of registered addresses along one walking or bus route.
Counts a corridor either side of the line, a radius around each stop, or
both, and returns exact numbers per leg and per stop with nameless pins and
their distances. Never an estimate and never partial: the answer is complete
or the call fails without a charge.
Returns: { shape: 'route', profile, measure, detail, datasetVersion, complete,
lengthMiles, corridorMiles, stopRadiusFeet, parcelAllowanceFeet, units,
total, corridorTotal, stopsTotal, breakdown {street, housed, homeless,
incarcerated}, legs: [ {leg, fromStop, toStop, lengthMiles, count} ],
stops: [ {stopId, alongMiles, count, nearestFeet, markerIds} ],
markers: [ {id, lat, lng, precision, addressType, distanceMiles, leg,
alongMiles, nearestStop, stopDistanceFeet} ], groups[], approximate {count,
areas[]}, unplaced {count, states}, externalId, notice, routeNotice }.
- `total` = distinct people with a street address in the corridor or a
stop's reach; leg counts sum to `corridorTotal`.
- Pins carry NO NAMES. A `groups` entry (several people at one address) and
an `approximate.areas` entry (people placed only at the middle of a ZIP,
city or county; never in `total`) open with map_group.
- To see who one marker is, call map_open_record with its `id` — a
separate charge at the account's record-open rate (published price
$0.035 per open; an account's agreed rate may differ). Open only the
records the user asks for, not every marker on the route.
- More than 300 pins at detail=full is a 422 `route_too_many_people` that
carries the exact counts and is not charged: use detail='count' or split
the route.
A count shows REGISTERED ADDRESSES, NOT WHERE ANYONE IS, and is not a rating
of the route. Never describe a route as safe or unsafe; relay `notice` and
`routeNotice`. It supports the user's process; it is not a legal
determination.
Billing: route units, each one map request ($2 per 1,000): one per started
mile of measured corridor plus one per 10 stops when stop radii are measured
(minimum 1); `units` in the answer says how many. detail='count' costs the
same. E.g. a 17.4-mile bus route with 35 stops = 18 + 4 = 22 units. Test
mode is free. The Map API must be turned on for the account.
Auth: uses the caller's X-API-Key (request header or OFFENDERSEARCH_API_KEY env).
View input schema
{
"type": "object",
"properties": {
"path": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"items": {
"items": {
"type": "number"
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "The route line: a GeoJSON LineString {'type':'LineString','coordinates':[[lng,lat],...]} (or a Feature holding one), or a plain list [[lng, lat], ...] in GeoJSON order. Send at most one of path or polyline.",
"title": "Path"
},
"polyline": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The route line as an encoded polyline (Google = precision 5; Mapbox/OSRM/Valhalla = precision 6), instead of path.",
"title": "Polyline"
},
"polyline_precision": {
"anyOf": [
{
"enum": [
5,
6
],
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "Precision of `polyline`: 5 (Google, the default) or 6 (Mapbox/OSRM/Valhalla).",
"title": "Polyline Precision"
},
"stops": {
"anyOf": [
{
"items": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"items": {
"type": "number"
},
"type": "array"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Stops along the route, in order: [{'id':'s1','lng':...,'lat':...}, ...] or [[lng, lat], ...]. Ids default to s1, s2, .... With no path or polyline, 2+ stops are joined by straight lines. Walk: up to 50 stops; bus: up to 150.",
"title": "Stops"
},
"profile": {
"anyOf": [
{
"enum": [
"walk",
"bus"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "walk (default; up to 15 miles, stop radius 500 ft) or bus (up to 60 miles, stop radius 1,000 ft).",
"title": "Profile"
},
"measure": {
"anyOf": [
{
"enum": [
"corridor",
"stops",
"both"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "What to count: the corridor either side of the line, a radius around each stop, or both. Default: both when stop_radius_feet is sent, otherwise corridor (stops when there is no line and fewer than 2 stops).",
"title": "Measure"
},
"corridor_miles": {
"anyOf": [
{
"maximum": 0.25,
"minimum": 0.02,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Corridor width either side of the line, in miles, 0.02 to 0.25 (default 0.1).",
"title": "Corridor Miles"
},
"stop_radius_feet": {
"anyOf": [
{
"maximum": 2640,
"minimum": 100,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Radius around each stop, in feet, 100 to 2,640 (default walk 500, bus 1,000).",
"title": "Stop Radius Feet"
},
"parcel_allowance_feet": {
"anyOf": [
{
"maximum": 500,
"minimum": 0,
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Feet added to the stop radius, 0 to 500, to allow for the distance between a geocoded point and the property line.",
"title": "Parcel Allowance Feet"
},
"detail": {
"default": "full",
"description": "full = counts plus nameless pins (default); count = counts only, same price, never refused for too many pins.",
"enum": [
"full",
"count"
],
"title": "Detail",
"type": "string"
},
"housing": {
"anyOf": [
{
"items": {
"enum": [
"housed",
"homeless",
"incarcerated"
],
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"description": "Keep only people with one of these housing statuses.",
"title": "Housing"
},
"street_only": {
"default": false,
"description": "If true, keep only people with an exact street address.",
"title": "Street Only",
"type": "boolean"
},
"sandbox": {
"default": false,
"description": "If true, answer in test mode: made-up people in the real response shape. Needs no plan and is never billed.",
"title": "Sandbox",
"type": "boolean"
},
"external_id": {
"anyOf": [
{
"maxLength": 100,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Your own reference for this route (up to 100 characters), echoed back as `externalId`.",
"title": "External Id"
}
},
"title": "map_routeArguments"
}