# Near an address

> Find everyone within a radius of a point with a centre and a distance in miles, read the distance to each pin, and show a plain count badge with no pins at all.

- **HTML:** https://offendersearch.app/docs/map/near-an-address
- **Base URL:** https://api.offendersearch.app
- **Authentication:** `X-API-Key` request header
- **Map API reference as markdown:** https://offendersearch.app/docs/map.md

## 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.

GET /v1/map/viewport

```bash
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

200 OK

```json
{
  "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
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `center`, `radiusMiles` | The circle that was answered. |
| `withinRadius` | The exact number of people inside the circle, at every detail level. |
| `total` | The same number: people inside the circle. |
| `markers[].distanceMiles` | The distance from the centre to the pin. Many-people pins and area pins carry it too. |

- 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`.

GET /v1/map/viewport

```bash
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
```

200 OK

```json
{
  "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](https://offendersearch.app/docs/map/access.md).

---

## Related

- Previous: [Open a record](https://offendersearch.app/docs/map/open-a-record.md)
- Next: [Drawn areas & routes](https://offendersearch.app/docs/map/drawn-areas.md)
- Index: [Map API reference](https://offendersearch.app/docs/map.md)