Near an address

A centre and a radius

For “who is near this address”, send a point and a distance instead of a box: center=lat,lng and radiusMiles. The radius is 0.1 to 100 miles.

curl -G https://api.offendersearch.app/v1/map/viewport \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -d center=39.9612,-82.9988 \
  -d radiusMiles=0.5 \
  -d sandbox=true

You supply the coordinates. Turn a typed address into a latitude and longitude with the geocoder you already use.

The response

{
  "mode": "markers",
  "center": [39.9612, -82.9988],
  "radiusMiles": 0.5,
  "withinRadius": 3,
  "total": 3,
  "markers": [
    {
      "id": "mk_…",
      "lat": 39.96301, "lng": -82.99512,
      "precision": "street",
      "addressType": "home",
      "label": "Sample J. Tester",
      "distanceMiles": 0.24
    }
  ]
}

• The detail level follows the same zoom rules as a box. A small radius is answered with pins or named pins; a large one with clusters.
• Only what is inside the circle comes back, not everything in the box around it.
• Markers are sorted nearest first, so the array is already a “nearest to you” list.
• Send zoom if you want a particular level. Without it, the radius picks one.

A count badge

For a line such as “3 within half a mile” on a listing page, you need a number and no pins. Add detail=count.

curl -G https://api.offendersearch.app/v1/map/viewport \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -d center=39.9612,-82.9988 \
  -d radiusMiles=0.5 \
  -d detail=count \
  -d sandbox=true

{
  "mode": "count",
  "center": [39.9612, -82.9988],
  "radiusMiles": 0.5,
  "withinRadius": 3,
  "total": 3,
  "breakdown": {
    "street": 3, "housed": 2, "homeless": 0, "incarcerated": 0
  },
  "clusters": [],
  "markers": [],
  "areas": []
}

• The answer has mode: "count", the totals and the breakdown. clusters, markers and areas are empty.
• It is one map request.
• It returns no marker ids, so nothing can be opened from it.

Keeping a count

A count for a fixed address changes slowly. You may keep it on your side for up to 24 hours and show it to every visitor of that page, instead of asking again on each page view. Use the address as the key.

This is for counts only. Pins and names carry marker ids that belong to one response. Do not keep them for other visitors.

Near me, on a phone

Use the device’s location as center. A phone app calls through your server. See Access & keys.