# Around an address

> Everything near an address or point, grouped and ranked, with an activity summary.

Source: https://api.tailend.dev/docs/around-an-address

Three endpoints answer "what is near here?". Pick by what you have and what
you want back.

| Endpoint | Give it | Get back |
| --- | --- | --- |
| [`/v1/{metro}/around`](https://api.tailend.dev/docs/api/search-around-address.md) | An address, or `lat`/`lng` | Everything nearby in five ranked groups, an activity summary, facets and a coverage note |
| [`/v1/{metro}/nearby`](https://api.tailend.dev/docs/api/list-nearby.md) | `lat`/`lng` | One flat list, nearest first, with the distance on every row |
| [`/v1/{metro}/activity`](https://api.tailend.dev/docs/api/get-activity.md) | An address, or `lat`/`lng` | One comparable 0 to 100 activity score, its components, and the listings nearby |

## Search around an address

```bash
curl -G -H "X-API-Key: $TAILEND_API_KEY" \
  --data-urlencode "address=1500 Market St, Philadelphia, PA" \
  --data "radius_m=1600" \
  https://api.tailend.dev/v1/philadelphia/around
```

```javascript
const params = new URLSearchParams({ address: "1500 Market St, Philadelphia, PA", radius_m: "1600" });
const res = await fetch(`https://api.tailend.dev/v1/philadelphia/around?${params}`, {
  headers: { "X-API-Key": process.env.TAILEND_API_KEY },
});
const { data } = await res.json();
console.log(data.location, data.activity, Object.keys(data.results));
```

One response carries:

- `location`: the resolved address, so you can see which reading of an
  ambiguous address was used.
- `activity`: a header with the score, percentile, one sentence and its
  components.
- `results`: five ranked groups. Every item has `distance_m` and
  `walk_minutes`.
- `facets`: counts by type, age band, free or paid, and distance ring over the
  whole circle.
- `coverage`: how many nearby listings cannot be shown because they have no
  coordinates.

## The five groups

| Group | Holds |
| --- | --- |
| `happening_soon` | Dated events in the window |
| `recurring_programs` | Weekly or monthly series and drop-in classes |
| `classes_enrolling` | Term classes |
| `camps` | Camps |
| `places` | Places with no date of their own |

`happening_soon` and `recurring_programs` overlap by design; each item's
`also_in` names the other groups it appears in.

`limit` is per group. Each group returns its own `next_cursor`; pass it as
`cursor` to page that one group.

## Read coverage before you say "nothing"

An empty group with `coverage.hidden_nearby` above `0` means some nearby
listings are not visible to this endpoint, not that the area has nothing
happening. Say so rather than reporting an empty area.

## Window and filters

`from` and `to` are local calendar dates in the metro's timezone. `from`
defaults to today and `to` to `from` plus 30 days. Narrow with `ages`, `free`,
`types` and `min_confidence`; see the
[reference](https://api.tailend.dev/docs/api/search-around-address.md) for every parameter.

## Address or coordinates

Send `lat`/`lng` when you already have coordinates. Address lookups have their
own usage limits and can return `429` when that capacity is unavailable; the
coordinate form keeps working.