---
title: "Search nearby events"
method: POST
path: "/events"
---

# Search nearby events

`POST /events`

## Request

- Base URL: `https://localselections.com/api/v1`
- URL: `https://localselections.com/api/v1/events`
- Auth: API key in header `X-API-Key`

Stage 196: real nearby events for a category label (e.g. "Music", "Comedy", "Sports" — an unrecognized label maps to a sensible default rather than erroring, same as every other caller of searchNearbyEvents), merged from up to four real sources: Ticketmaster (onsale-only), first-party user/organizer submissions, official city open-data event calendars, and events found directly on a business's own site (schema.org/JSON-LD or a real RSS/iCal feed) — see the NearbyEvent schema's `origin`/`originLabel` fields. Each of the three free, first-party origins carries a `detailUrl` to a real, permanent LocalSelections event page when it clears that page's own content floor (null otherwise); a `ticketmaster`-origin result never gets one (see the NearbyEvent schema's `detailUrl` note) — use its `ticketUrl` instead. This is the same shared, rate-limited Ticketmaster pool every other event-consuming endpoint draws from (Stages 165/167) — a burst of calls can return a 503 high_demand (the pool-wide daily ceiling) or a 429 rate_limited (this caller's own per-day cap on uncached lookups) in addition to the usual v1 429. Requires the `events` scope. Costs 2 units of the key's rate-limit budget per call. Stage 198: a free-tier key is also separately capped at 80 calls/day to this endpoint specifically, on top of all of the above (see the 429 response) — commercial use is exempt.

## Request body

- object
  - `categoryLabel` string, required: e.g. "Music", "Comedy", "Sports", "Family".
  - `lat` number, required
  - `lng` number, required

## Response `200`

Nearby events for the requested category.

- object
  - `events` object[], required
    - `id` string, required
    - `name` string, required
    - `venueName` string, nullable
    - `date` string, nullable
    - `time` string, nullable
    - `distanceMiles` number, nullable
    - `address` string, nullable
    - `imageUrl` string, uri, nullable
    - `ticketUrl` string, uri, required
    - `origin` 'ticketmaster' | 'user_submitted' | 'municipal' | 'web_schema' | 'rss_ical', required: Stage 182/183/186: which source this event came from — never blended indistinguishably. "municipal" is an official city open-data event calendar (currently New York, NY and Los Angeles, CA). "web_schema"/"rss_ical" are found directly on a business's own site (schema.org/JSON-LD markup, or a real structured RSS/iCal feed).
    - `originLabel` string: Stage 196: human-readable form of `origin` (e.g. "Ticketmaster", "the venue's own website"). Only present on /events (not /spin or /bracket's narrowed/candidate events, which predate this field).
    - `detailUrl` string, uri, nullable: Stage 196: a real, permanent LocalSelections detail page for this exact event, reusing that page's own content floor (enough real name/date/location, not ended). Always null for a `ticketmaster`-origin event — resolving it would require a second, separately-billed Ticketmaster API call per event, multiplying real spend against the same shared daily ceiling every other Ticketmaster call already draws from; use `ticketUrl` (the original listing) for those instead. Only present on /events (not /spin or /bracket, which predate this field).

## Other responses

- `400`: The request body failed validation.
- `401`: Missing or invalid API key.
- `403`: The API key does not carry the scope this endpoint requires (see the "Requires the ... scope" note on each path, or call GET /introspect to see a key's real granted scopes).
- `429`: Rate limit exceeded for this API key. The budget is 30 units/60s for keys owned by an unsubscribed account, 120 units/60s for a subscribed account's keys (Stage 60) — shared across every endpoint, but each endpoint spends a different number of units per call rather than always 1 (Stage 104): search/groups_host/groups_join/places/movies cost 1, surprise_me/events cost 2, spin costs 3, bracket costs 4. Call GET /introspect to see a key's real remaining budget before it runs out. Separately, these three endpoints also enforce their own free-tier-only daily ceiling per key (`error: "daily_limit_exceeded"`) — resets at UTC midnight, and does not apply to a commercial-tier key. Contact support@localselections.com for commercial/high-volume access.
- `502`: An upstream data source failed or returned nothing usable.
- `503`: The shared Ticketmaster event budget for today is exhausted (error: "high_demand"). Try again after the daily reset.

---

[API](https://skmtc.dev/localselections/apis/localselections-public-api.md) · [All operations](https://skmtc.dev/localselections/apis/localselections-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/localselections/apis/localselections-public-api/revisions/a24e9598add4?raw)