# Retrieve area activity

> Returns a single comparable activity score for a point (unlike /around, which resolves an address and returns grouped, ranked results — this endpoint's job is the one number, not a result set), the components behind it, and the specific listings nearby.

Source: https://api.tailend.dev/docs/api/get-activity

```http
GET https://api.tailend.dev/v1/{metro}/activity
X-API-Key: $TAILEND_API_KEY
```

Returns a single comparable activity score for a **point** (unlike
`/around`, which resolves an **address** and returns grouped,
ranked results — this endpoint's job is the one number, not a
result set), the components behind it, and the specific listings
nearby.

Give **either** `lat` + `lng` **or** `address`. An `address` is
resolved to a point server-side and biased to the metro. A request
that exceeds the key's geocoding allowance returns `429` naming the
reset. `data.resolved_address` reports the address that was used and
how it was resolved (see `ResolvedLocation`); it is `null` for the
`lat`/`lng` form.

Counted rows are published, active, and coordinate-bearing, excluding
a source marked `gone`, anything quarantined, and coordinates that
are an approximate resolution rather than a known place. Classes and
camps whose term has already ended are not counted: `activity_score`
reflects what is ahead, not what has happened.

`activity_score` is 0-100 and absolute, so it is comparable between
metros and over time. `percentile` ranks the same point against the
metro's reference distribution; it is `null` until comparison data
is available. Diagnostic details are available only to internal keys.

Returns 503 when this endpoint, or address resolution for the
`address` form, is unavailable.

Authorization: send your key in the `X-API-Key` header. Available on every plan.

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `metro` | string | yes | Metro slug from /v1/metros (e.g. philadelphia). |

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `lat` | number | no | Latitude of the point to score. |
| `lng` | number | no | Longitude of the point to score. |
| `address` | string | no | A street address to resolve server-side instead of sending a point. |
| `radius_m` | integer | no | Radius in metres. |
| `days` | integer | no | How far ahead the event window reaches, in days. |
| `include` | array of string | no | Opt into a block the lean default response leaves out. |

## Example request

```bash
curl -sS \
  -H "X-API-Key: $TAILEND_API_KEY" \
  "https://api.tailend.dev/v1/philadelphia/activity"
```

## Responses

### 200

The activity of the point.

```json
{
  "data": {
    "point": {
      "lat": 1,
      "lng": 1
    },
    "radius_m": 1,
    "days": 1,
    "components": {
      "events_30d": 1,
      "events_per_week": 1,
      "recurring_programs": 1,
      "classes": 1,
      "camps": 1,
      "places_total": 1,
      "places_by_type": {}
    },
    "activity_score": 1,
    "summary": "example",
    "evidence": [
      {
        "listing_id": "00000000-0000-4000-8000-000000000001",
        "type": "event",
        "name": "example",
        "distance_m": 1
      }
    ]
  },
  "meta": {
    "metro": "example",
    "radius_m": 1,
    "days": 1,
    "generated_at": "2026-09-24T12:00:00.000Z"
  }
}
```

### 400

Malformed or contradictory parameters (lat without lng, to before from, unknown category), or a cursor this API did not issue for this exact request — replayed from another endpoint, resource, metro or filter set, hand-crafted, or altered.

```json
{
  "error": {
    "code": "bad_request",
    "message": "radius_m: must be at least 100",
    "details": {
      "param": "radius_m"
    },
    "request_id": "req_dfbc3295a8382b05"
  }
}
```

### 401

Missing, unknown or revoked X-API-Key.

```json
{
  "error": {
    "code": "unauthorized",
    "message": "missing X-API-Key header",
    "request_id": "req_90e63908273f6bff"
  }
}
```

### 403

Two different reasons share this status.

```json
{
  "error": {
    "code": "forbidden",
    "message": "key is not scoped to metro 'boston'",
    "details": {
      "metros": [
        "philadelphia"
      ]
    },
    "request_id": "req_9e7a750acef48ab2"
  }
}
```

### 404

No published, active resource with that id (or unknown metro).

```json
{
  "error": {
    "code": "not_found",
    "message": "unknown metro 'boston'",
    "request_id": "req_7431b51e10ec2b77"
  }
}
```

### 405

The path exists; the method does not.

```json
{
  "error": {
    "code": "method_not_allowed",
    "message": "POST is not allowed on this path; this API is read-only",
    "details": {
      "allow": [
        "GET",
        "HEAD",
        "OPTIONS"
      ]
    },
    "request_id": "req_01J9Z3"
  }
}
```

### 429

A limit was reached.

```json
{
  "error": {
    "code": "rate_limited",
    "message": "3 requests per minute exceeded",
    "request_id": "req_06bfd3c2d5e8aa9f"
  }
}
```

### 500

A bug on our side.

```json
{
  "error": {
    "code": "internal",
    "message": "internal error",
    "request_id": "req_01J9Z3"
  }
}
```

### 501

This endpoint or feature is not available and will not become available without a configuration change — for ?address=, this means no geocoder is configured.

```json
{
  "error": {
    "code": "not_implemented",
    "message": "this endpoint is not enabled on this deployment; it is not a fault and retrying will not help",
    "request_id": "req_01J9Z3"
  }
}
```

### 503

A transient outage: a dependency could not be reached or did not answer in time.

```json
{
  "error": {
    "code": "unavailable",
    "message": "the service is temporarily unable to serve this request; retry after the interval in Retry-After",
    "request_id": "req_01J9Z3"
  }
}
```