GET/v1/{metro}/activityall plans

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.

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.

Try this requestRun it with sample data, no key needed. Paste a key to run it live.

Example request

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

Example response · 200

{
  "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"
  }
}

API key Remember for this tab

Try any request with sample data, no key needed. Available on every plan.

metrostringrequiredpath

Metro slug from /v1/metros (e.g. philadelphia).

Optional parameters (6)

latnumberoptionalquery

Latitude of the point to score.

lngnumberoptionalquery

Longitude of the point to score.

addressstringoptionalquery

A street address to resolve server-side instead of sending a point.

radius_mintegeroptionalquery

Radius in metres.

daysintegeroptionalquery

How far ahead the event window reaches, in days.

includearray of stringoptionalquery

Opt into a block the lean default response leaves out.

Response

A 200 returns application/json with these fields.

dataActivityalways present
- pointobjectalways present
  - latnumber
  - lngnumber
- radius_mintegeralways present
- daysintegeralways present
- metrostring · nullable
- generated_atstring (date-time)
- componentsActivityComponentsalways present
  The counts and distances behind activity_score, computed over the rows described on the operation.
  - events_30dintegeralways present
    Events starting inside the window (days, default 30).
  - events_per_weeknumberalways present
    events_30d normalised to a week, so a 7-day and a 90-day window are comparable.
  - recurring_programsintegeralways present
    Distinct events in the window flagged is_recurring — a weekly storytime, not a one-off.
  - classesintegeralways present
    Live classes whose term has not ended (or that are ongoing).
  - campsintegeralways present
    Live camps whose span has not ended. Past summer camps are not counted.
  - places_totalintegeralways present
  - places_by_typeobjectalways present
    Place counts keyed by PlaceTypeHint.
  - nearest_library_minteger · nullable
    Metres to the nearest library. Null when there is none in the radius.
  - nearest_park_minteger · nullable
  - nearest_playground_minteger · nullable
    Nearest play_space, or a place whose name or tags say playground. playground is not a PlaceTypeHint.
  - nearest_museum_minteger · nullable
  - free_sharenumber · nullable
    Share of the window's events that are free, 0-1. Null when there are no events to take a share of.
  - age_band_coverageobject
    Which of the four age bands (baby, toddler, young_kids, bigger_kids) anything nearby serves.
    bandsobject
    bands_presentinteger
    bands_possibleinteger
  - weekday_weekend_splitobject
    Events in the window by local day of week.
    weekdayinteger
    weekendinteger
  - daytime_evening_splitobject
    Events in the window by local start hour; evening is 16:00 or later.
    daytimeinteger
    eveninginteger
- score_partsobject
  Diagnostic scoring detail. Present only to internal keys that request diagnostics.
  - programmingnumber
  - placesnumber
  - recurringnumber
  - accessnumber
  - breadthnumber
- activity_scorenumberalways present
  0-100, absolute and comparable across metros and over time.
- percentileinteger · nullable
  Where this score falls against the metro's reference distribution. Null until enough comparison data is available.
- percentile_basisstring
  Diagnostic context for the percentile. Present only to internal keys that request diagnostics.
- summarystringalways present
  One sentence a listing page can print as-is.
- evidencearray of ActivityEvidencealways present
  - listing_idstring (uuid)always present
    Fetch the full row from /v1/{type}s/{listing_id}.
  - typestringalways present
    The listing's type. ongoing rows are served only on /v1/changes today.
    eventclasscampplaceongoing
  - namestringalways present
  - distance_mintegeralways present
  - next_atstring (date-time) · nullable
    When it next happens. Null for a place.
  - type_hintstring · nullable
    play_spacemuseumparklibrarytheatersports_facilityfarmrestaurantothernull
  - is_freeboolean · nullable
- resolved_addressobject · nullable
  Present only when the request used address. Null for the lat/lng form.
  - querystring
  - formattedstring · nullable
  - place_idstring · nullable
  - sourcestring
    cachegeocoder
metaobjectalways present
- metrostring
- radius_minteger
- daysinteger
- generated_atstring (date-time)

Status codes

200
The activity of the point.
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.
401
Missing, unknown or revoked X-API-Key. Also returned when the key record itself does not validate — the server fails closed and logs why rather than assuming anything about a row it cannot vouch for, and when the value is not shaped like a key (tl_ + 8 hex + _ + 48 hex). The message is invalid API key; the reason is not disclosed. The one exception is a credential shaped like a different kind of token, whose 401 explains it is the wrong credential for /v1 rather than repeating the generic message.
403
Two different reasons share this status. Read error.code.
Show more
forbidden — the key is valid but its scopes exclude this metro or resource type, or the client is inactive. Returned when the caller named the metro or type it was refused — in the path, or in ?metro=. Where the caller supplied only an identifier, an out-of-scope resource is a 404 instead; see NotFound.

include_not_permitted (endpoints that take include= only) — the key is valid and in scope, but is not entitled to a requested include= add-on (details.include names it). Add include_mode=lenient to get a 200 without the block instead of this. See Shaping responses.
404
No published, active resource with that id (or unknown metro).
Show more
Also returned when the resource exists but sits in a metro outside the key's scopes.metros, on the routes that take an identifier rather than a metro: /v1/{type}/{id}, /v1/{type}/slug/{slug} and /v1/organizations/{id}. The metro there is discovered from the row, not named by the caller, so a 403 would confirm that a guessed id or slug is real and say which metro it is in. The two cases are deliberately indistinguishable — same code, same message, same absent details.

Naming the metro is a different question and still gets the explicit 403 with the key's own scopes: /v1/boston/events, or ?metro=boston on a slug lookup.
405
The path exists; the method does not. Every route on this API is a read, so Allow is always GET, HEAD, OPTIONS. A method on a path that does not exist is a 404 instead — 405 is only ever sent where there is a target resource to refuse.
429
A limit was reached. Branch on error.code, not on the status — two different limits share this status:
Show more
- rate_limited — the per-minute rate. Retry-After is seconds, and retrying after it succeeds.
- rate_limited can also mean address lookups are temporarily unavailable. The response explains the condition and provides Retry-After; callers that already have coordinates can send lat/lng instead.
- quota_exceeded — the monthly allowance, or a client's hard cap. Retry-After points at the start of the next UTC month and can therefore be very large; details carries plan, monthly_limit, used and resets_at. Backing off will not help before the reset — the plan has to change. This is a 429; 402 is reserved.
500
A bug on our side. The message is always the constant internal error; details are never included in the body. Retry once with backoff, then contact support with the request_id.
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.
Show more
Nothing is failing, so do not retry and do not back off: there is no Retry-After, and the answer will not change inside any timeout you set. Treat the feature as switched off, disable it in your UI, and use the alternative the message names where there is one (lat/lng instead of address).

The message is a constant per endpoint family and names no internal object. Include the request_id when contacting support.
503
A transient outage: a dependency could not be reached or did not answer in time. This is the 5xx worth retrying — Retry-After says how long, and the same request is expected to succeed afterwards.

Like every other error here, the message names no internal detail.

Every error uses the same envelope; branch on error.code. See Errors.

Ctrl Enter to send

Request

GEThttps://api.tailend.dev/v1/philadelphia/activity

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

const res = await fetch("https://api.tailend.dev/v1/philadelphia/activity", {
  headers: { 'X-API-Key': '$TAILEND_API_KEY' },
});
const body = await res.json();
console.log(res.status, body);

import os
import requests

response = requests.get(
    "https://api.tailend.dev/v1/philadelphia/activity",
    headers={'X-API-Key': os.environ['TAILEND_API_KEY']},
)
response.raise_for_status()
print(response.json())

ResponseSample

Showing sample data. Paste a key to run it live. Get a key

The activity of the point.

{
  "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"
  }
}

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.

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

Missing, unknown or revoked X-API-Key.

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

Two different reasons share this status.

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

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

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

The path exists; the method does not.

{
  "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"
  }
}

A limit was reached.

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

A bug on our side.

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

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

{
  "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"
  }
}

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

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