# Drawn areas & routes

> Send a polygon, or a route with a buffer either side, and get everyone inside the shape: a school zone, a delivery area or a walking route, in one map request.

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

## The request

`POST /v1/map/area` returns everyone inside a shape you draw: a school zone, a delivery area, a walking route. It is one map request. Send one of `polygon` or `route`.

## A polygon

POST /v1/map/area

```bash
curl -X POST https://api.offendersearch.app/v1/map/area \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "polygon": [
      [-83.01, 39.96], [-82.99, 39.96],
      [-82.99, 39.98], [-83.01, 39.98]
    ],
    "sandbox": true
  }'
```

- 3 to 200 points.
- Each point is `[lng, lat]`: longitude first, as in GeoJSON.
- The ring is closed for you. You may repeat the first point at the end, or leave it out.
- A shape may not cross the date line or span half the globe.

## A route with a buffer

POST /v1/map/area

```bash
curl -X POST https://api.offendersearch.app/v1/map/area \
  -H "X-API-Key: $OFFENDERSEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "route": {
      "points": [
        [-83.01, 39.96], [-83.00, 39.97], [-82.99, 39.98]
      ],
      "bufferMiles": 0.25
    },
    "sandbox": true
  }'
```

- `points`: 2 to 200 points along the route, each `[lng, lat]`.
- `bufferMiles`: the distance either side of the line, 0.05 to 5 miles.
- The answer is everyone within that distance of any part of the route.
- A route may not cross the date line or span half the globe.

## Body fields

| Field | Meaning |
| --- | --- |
| `polygon` | An array of 3 to 200 `[lng, lat]` points. |
| `route` | An object with `points` and `bufferMiles`. |
| `zoom` | As on the viewport route. |
| `format` | `json` or `geojson`. |
| `detail` | `full` or `count`. |
| `housing` | A comma-separated string, or an array such as `["homeless", "incarcerated"]`. |
| `precision` | `street` for exact street addresses only. `any` is the default. |
| `sandbox` | `true` for [test mode](https://offendersearch.app/docs/map/test-mode.md). |

## The response

The response is the viewport response for the shape’s bounding box, limited to what is inside the shape. It has one more field: `"shape": "polygon"` or `"shape": "route"`.

- The detail level follows the same zoom rules as a view. Send `zoom` to ask for a level, or leave it out and the size of the shape picks one.
- In `pins` and `markers` mode, `total` is exact.
- In `clusters` mode, a cluster is included when its centre is inside the shape, and the response carries `"totalIsEstimate": true`. Zoom in, or draw a smaller shape, for an exact number.
- Marker ids, group ids and the records route work exactly as they do from a view.

## Caching

An area answer carries `Cache-Control` and no `ETag`, so there is no `304` for a drawn shape. Keep the answer on your side while the shape is on screen.

## Errors

A shape that cannot be read answers `422 invalid_shape`: both or neither of `polygon` and `route`, too few or too many points, a point that is not `[lng, lat]`, a buffer outside the range, or a shape that crosses the date line. The other viewport errors apply too. See [Limits & errors](https://offendersearch.app/docs/map/limits-and-errors.md).

## Watching an area

This route answers once. To be told when someone new appears in an area, create a location monitor. See [location monitoring](https://offendersearch.app/docs/monitoring/location-monitoring.md).

---

## Related

- Previous: [Near an address](https://offendersearch.app/docs/map/near-an-address.md)
- Next: [Filters & lists](https://offendersearch.app/docs/map/filters-and-lists.md)
- Index: [Map API reference](https://offendersearch.app/docs/map.md)