map_route
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).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | 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. | |
| stops | No | 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. | |
| detail | No | full = counts plus nameless pins (default); count = counts only, same price, never refused for too many pins. | full |
| housing | No | Keep only people with one of these housing statuses. | |
| measure | No | 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). | |
| profile | No | walk (default; up to 15 miles, stop radius 500 ft) or bus (up to 60 miles, stop radius 1,000 ft). | |
| sandbox | No | If true, answer in test mode: made-up people in the real response shape. Needs no plan and is never billed. | |
| polyline | No | The route line as an encoded polyline (Google = precision 5; Mapbox/OSRM/Valhalla = precision 6), instead of path. | |
| external_id | No | Your own reference for this route (up to 100 characters), echoed back as `externalId`. | |
| street_only | No | If true, keep only people with an exact street address. | |
| corridor_miles | No | Corridor width either side of the line, in miles, 0.02 to 0.25 (default 0.1). | |
| stop_radius_feet | No | Radius around each stop, in feet, 100 to 2,640 (default walk 500, bus 1,000). | |
| polyline_precision | No | Precision of `polyline`: 5 (Google, the default) or 6 (Mapbox/OSRM/Valhalla). | |
| parcel_allowance_feet | No | Feet added to the stop radius, 0 to 500, to allow for the distance between a geocoded point and the property line. |