map_viewport
Get what to draw for one map view: clusters, pins, or named pins.
Send the view as `bbox`, or as `lat` + `lng` + `radius_miles`. The detail
returned depends on the zoom the view is answered at (the response states it
in `zoom`):
- zoom 3-12 -> mode 'clusters': a count per grid cell. Each cluster has
`count`, `bbox`, `breakdown` and `expansionZoom` (fit the map to `bbox` at
that zoom and the cluster comes apart).
- zoom 13-14 -> mode 'pins': one pin per address, position only, no name.
- zoom 15+ -> mode 'markers': pins with `label` (first initial and last
name), `housingStatus`, `hasPhoto`, `registryState`.
A close view holding more than 300 pins is answered as clusters instead.
Returns: { mode, zoom, bbox, datasetVersion, total, breakdown {street, housed,
homeless, incarcerated}, clusters[], markers[], areas[], unplaced {count,
states}, notice }. In radius mode also `center`, `radiusMiles` and
`withinRadius` (exact), and each marker has `distanceMiles`.
- A marker with `id: null` and a `groupId` stands for several people at one
address: call map_group with that `groupId`.
- `areas` are people placed only at the middle of a ZIP, city or county;
each has a `groupId` too. Never describe them as being at an exact spot.
- `unplaced` counts people in the states this view touches who have no
mappable address. Mention it rather than implying the map shows everyone.
- To see who one marker is, call map_open_record with its `id`.
A pin shows a REGISTERED ADDRESS, not a person's current location — say so
when you describe a result (`notice` carries the sentence).
Billing: one map request per call ($2 per 1,000), whatever the view holds. Marker and group
ids work for 24 hours. The Map API must be turned on for the account
(the API answers 403 `map_not_enabled` otherwise); `sandbox=true` works
without it.
Auth: uses the caller's X-API-Key (request header or OFFENDERSEARCH_API_KEY env).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude of the centre, instead of bbox (send with lng and radius_miles). | |
| lng | No | Longitude of the centre, instead of bbox (send with lat and radius_miles). | |
| bbox | No | The view as 'west,south,east,north' in degrees, e.g. '-83.5,39.6,-82.4,40.3'. Any size. Send this OR lat/lng with radius_miles, not both. | |
| zoom | No | Optional map zoom, 0 to 22. Decides the detail: 3-12 clusters, 13-14 pins without names, 15+ pins with names. Omit it and the zoom is worked out from the size of the view. | |
| detail | No | full = clusters or pins (default); count = numbers only. | full |
| housing | No | Keep only people with one of these housing statuses. | |
| sandbox | No | If true, answer in test mode: made-up people (labels start with 'Sample') in the real response shape. Needs no plan and is never billed. | |
| street_only | No | If true, keep only people with an exact street address. | |
| radius_miles | No | Radius in miles around lat/lng, 0.1 to 100. |