Routes, stops and corridors

Route search: who is registered along a route

POST /v1/map/route answers who is registered along a route, exactly: within a corridor either side of a line, within a radius around each stop, or both. The answer counts each leg and each stop, and places every pin on the route. It shows registered addresses, not where anyone is.

curl -X POST https://api.offendersearch.app/v1/map/route \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "bus",
    "polyline": "o|{rFnuqyN_v@oi@o}@g^",
    "stops": [
      {"id": "stop-1", "lng": -82.9988, "lat": 39.9612},
      {"id": "stop-2", "lng": -82.9920, "lat": 39.9700},
      {"id": "stop-3", "lng": -82.9870, "lat": 39.9800}
    ],
    "corridorMiles": 0.1,
    "stopRadiusFeet": 1000,
    "externalId": "route-7-AM",
    "sandbox": true
  }'

A route answer gives exact counts per leg and per stop, with pins and distances but no names. The full record behind a pin is opened, and billed, one at a time.

• Exact, never estimated. Only the map tiles the corridor and the stop radii touch are read, and every address in them is measured. A long diagonal route reads a strip, not its bounding box.
• One call for many routes. POST /v1/map/routes takes up to 50, all or nothing. See the batch route.
• Test mode works here too. Send "sandbox": true; the example above has people around it.

Who it is for, with pricing worked out for a district and a walking app: the sex offender route API page.

Route path formats: GeoJSON, points and polylines

Send the line in the form your routing tool already gives you. Send at most one of path, points and polyline.

• A line may have up to 50,000 points. One with more than 2,000 is simplified to within about 5 metres first, so a turn-by-turn line from a directions service fits.
• A polyline read at the wrong precision lands far from where it was drawn. It is refused with invalid_polyline, never answered somewhere else.
• A route may not cross the date line or span half the globe.

Route corridor and bus stop radius

Leave measure out and it follows what you sent: both when stopRadiusFeet is sent (stops when there is no line), otherwise corridor.

• profile is walk (the default) or bus. It sets the limits and the default stop radius: 500 feet walking, 1,000 feet by bus.
• parcelAllowanceFeet adds 0 to 500 feet to every stop radius. A registered address is one geocoded point; the allowance stands in for the distance from that point to the property line.
• Stops are in route order. The line is cut into legs at the stops, and each stop is placed along the line in that order, so a loop that ends where it starts puts its last stop at the end.
• Stop ids are yours. Answers name a stop by its id only. A label is accepted and never echoed.

Route stop fields in a request: the MapRouteStopInput object

One stop in stops[] of a route request. A bare [lng, lat] pair is accepted too, and gets the id s1, s2, … by its position.

Returned or accepted by POST /v1/map/route, POST /v1/map/routes.

Route legs, stops and alongMiles

{
  "shape": "route",
  "profile": "bus",
  "measure": "both",
  "detail": "full",
  "datasetVersion": "2026-10-18",
  "complete": true,
  "lengthMiles": 1.456,
  "corridorMiles": 0.1,
  "stopRadiusFeet": 1000.0,
  "parcelAllowanceFeet": 0.0,
  "units": 3,
  "tilesRead": 4,
  "total": 9,
  "corridorTotal": 8,
  "stopsTotal": 4,
  "breakdown": {"street": 9, "housed": 3, "homeless": 0, "incarcerated": 0},
  "legs": [
    {"leg": 1, "fromStop": "stop-1", "toStop": "stop-2", "lengthMiles": 0.687, "count": 5},
    {"leg": 2, "fromStop": "stop-2", "toStop": "stop-3", "lengthMiles": 0.769, "count": 3}
  ],
  "stops": [
    {"stopId": "stop-1", "alongMiles": 0.0, "count": 2, "nearestFeet": 412,
     "markerIds": ["mk_Qa8…", "mk_Rt2…"]},

• total is distinct people with a street address in the corridor or within a stop’s reach. corridorTotal and stopsTotal split it; a person can be in both.
• legs[] counts the corridor leg by leg. Each person is counted on the leg of their nearest point of the line, so the leg counts add up to corridorTotal.
• stops[] gives each stop’s count, the distance to the closest address in nearestFeet, and the pins in reach in markerIds.
• Pins are in markers (one person) and groups (several people at one address), ordered along the line. In the corridor a pin has distanceMiles, leg and alongMiles; on a route with stops it has nearestStop and stopDistanceFeet.
• routeNotice says how the route was measured. Show it next to the counts.
• units is what the route is billed as. See route units.

Route leg fields: the MapRouteLeg object

The line between two stops, in legs[]. With fewer than two stops the whole line is one leg. Each person in the corridor counts on the leg of their nearest point of the line, so the leg counts add up to corridorTotal.

Returned or accepted by POST /v1/map/route, POST /v1/map/routes.

Route stop fields in an answer: the MapRouteStop object

One stop, as answered, in stops[], in the order sent.

Returned or accepted by POST /v1/map/route, POST /v1/map/routes.

Route pin fields: the MapRouteMarker object

One person at one exact street address near the route, in markers[]. A position, its place on the route and an id. Never a name, on any plan.

Returned or accepted by POST /v1/map/route, POST /v1/map/routes.

Route group pin fields: the MapRouteGroup object

Several people registered at one exact street address near the route, as one pin in groups[]. The people behind it open with GET /v1/map/groups/{groupId} (one map request per page, no names).

Returned or accepted by POST /v1/map/route, POST /v1/map/routes.

Approximate and unplaced people near a route

Some people are mapped only to the centre of a ZIP code, a city or a county. Their distance to the route is not known, so they are never counted in total. Those whose area centre falls in the map tiles the route touches are listed under approximate, with a count and one pin per area. Draw them so they do not look like an address.

unplaced counts people in the states the route touches who have no mappable address at all, as on a map view. Say so next to the counts, so a short list is not read as the whole list.

Route approximate-area fields: the MapRouteArea object

People mapped only to the centre of a ZIP code, city or county, in approximate.areas[]. Their distance to the route is not known, so they are listed here and never counted in total.

Returned or accepted by POST /v1/map/route, POST /v1/map/routes.

Never partial: exact route counts or a refusal

A route is answered whole, or refused with nothing charged. There is no estimated count and no cut-off list.

{
  "detail": {
    "code": "route_too_many_people",
    "message": "This route has 412 places to pin, more than the 300 one response carries. …",
    "counts": {
      "total": 398,
      "corridorTotal": 371,
      "stopsTotal": 64,
      "breakdown": {"street": 398, "housed": 120, "homeless": 9, "incarcerated": 0},
      "legs": [{"leg": 1, "fromStop": "stop-1", "toStop": "stop-2", "lengthMiles": 0.61, "count": 12}],
      "stops": [{"stopId": "stop-1", "alongMiles": 0.0, "count": 3, "nearestFeet": 288}],
      "approximate": {"count": 14},
      "units": 22
    },
    "maxMarkers": 300
  }
}

Route units: route corridor pricing

A route is $2.00 per 1,000 route units: 1 unit per started mile of corridor, plus 1 per 10 stops.

Worked example. A 17.42-mile bus route with a 0.1-mile corridor and 35 stops at 1,000 feet is 18 + 4 = 22 units, $0.044. Checking 300 such routes in each of 3 terms is 19,800 units, $39.60 a year in map requests.

• detail=count costs the same as a route with pins.
• A batch costs the sum of its routes, and nothing unless the whole batch answers.
• The same route asked again with If-None-Match answers 304, free. Test mode and errors are free.
• Opening a record behind a pin is one record open, $0.035 by default. See Billing.

No names on a route answer

A route answer carries positions, distances, counts and ids. It never carries a name, on any plan, and the markerFields: named plan setting does not apply to it.

The reason is the shape. A map view is bounded by a screen, and names start only from zoom 15, a few streets across. A route can run for 60 miles, so a named answer would be a list of names along a whole county. The record behind any pin is still one call away: pass its id to GET /v1/map/records/{markerId}, one record open.

For a map with name labels, request GET /v1/map/viewport at zoom 15 or closer for the part of the route on screen. That is an ordinary map view, one map request, with named pins.

Route limits for walk and bus profiles

GET /v1/map/status returns these under routes.profiles. An end user may check 20 different routes a day by default; see Daily limits.

Route profile limits: the MapRouteProfile object

The limits of one route profile, as GET /v1/map/status reports them under routes.profiles.

Returned or accepted by GET /v1/map/status.

Route API samples: curl, Node and Python

curl -X POST https://api.offendersearch.app/v1/map/route \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "bus",
    "polyline": "o|{rFnuqyN_v@oi@o}@g^",
    "stops": [
      {"id": "stop-1", "lng": -82.9988, "lat": 39.9612},
      {"id": "stop-2", "lng": -82.9920, "lat": 39.9700},
      {"id": "stop-3", "lng": -82.9870, "lat": 39.9800}
    ],
    "corridorMiles": 0.1,
    "stopRadiusFeet": 1000,
    "externalId": "route-7-AM",
    "sandbox": true
  }'

Route GeoJSON output

With "format": "geojson" a single route answers as a FeatureCollection of points, content type application/geo+json: one feature per marker (kind: "marker"), group (kind: "group") and approximate area (kind: "area"). Everything else, the counts, legs and stops included, is under meta. A batch answers in JSON only.

curl -X POST https://api.offendersearch.app/v1/map/route \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": {
      "type": "LineString",
      "coordinates": [[-82.9988, 39.9612], [-82.9920, 39.9700], [-82.9870, 39.9800]]
    },
    "format": "geojson",
    "sandbox": true
  }'

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-82.99863, 39.96133]},
      "properties": {
        "kind": "marker",
        "id": "mk_Qa8…",
        "precision": "street",
        "addressType": "home",
        "distanceMiles": 0.002,
        "leg": 1,
        "alongMiles": 0.078
      }
    },
    {
      "type": "Feature",
      "geometry": {"type": "Point", "coordinates": [-83.0114, 39.969]},
      "properties": {
        "kind": "area",
        "groupId": "mg_X1G…",
        "precision": "zip",
        "place": "43215",
        "count": 5
      }
    }
  ],
  "meta": {
    "shape": "route", "measure": "corridor", "units": 2, "total": 8,
    "legs": [{"leg": 1, "fromStop": null, "toStop": null, "lengthMiles": 1.456, "count": 8}],
    "approximate": {"count": 5, "areas": ["…"]},
    "notice": "A pin shows a registered address, not a person's current location."
  }
}

Batch route search: up to 50 routes

POST /v1/map/routes takes up to 50 routes, each shaped like a POST /v1/map/route body, and answers them in the order sent, each with its routeIndex.

• All or nothing. One refused route refuses the batch, with routeIndex naming it, and nothing is billed.
• One response for every route. A person near three routes is one record open when opened from this answer, and is counted once in uniquePeople.
• Billing is the sum of the routes’ units, in units.

curl -X POST https://api.offendersearch.app/v1/map/routes \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routes": [
      {"externalId": "route-7-AM", "profile": "bus", "polyline": "o|{rFnuqyN_v@oi@o}@g^",
       "stops": [[-82.9988, 39.9612], [-82.9870, 39.9800]], "stopRadiusFeet": 1000},
      {"externalId": "route-7-PM", "profile": "bus",
       "points": [[-82.9870, 39.9800], [-82.9988, 39.9612]], "detail": "count"}
    ],
    "sandbox": true
  }'

{
  "shape": "routes",
  "complete": true,
  "datasetVersion": "2026-10-18",
  "units": 4,
  "uniquePeople": 9,
  "routes": [
    {"routeIndex": 0, "shape": "route", "externalId": "route-7-AM", "total": 9, "…": "…"},
    {"routeIndex": 1, "shape": "route", "externalId": "route-7-PM", "total": 8, "…": "…"}
  ],
  "notice": "A pin shows a registered address, not a person's current location.",
  "sandbox": true
}

Route caching and end users

• A single route answer carries Cache-Control: private, max-age=300 and an ETag. Send it back in If-None-Match: the same route answers 304, with no body, free.
• Marker and group ids work for 24 hours, for your account only.
• A map browser key must send X-End-User on both route routes. See Platform integration.
• Pins from a route count toward the daily area limit like pins from a view (detail=count never does), and each end user may check 20 different routes a day by default. See Limits & errors.

Route search errors

Access errors (401, 403) and service errors are as on every map route. See Limits & errors.