Search Local Events
search_eventsSearch US local events near a place and within a date window: concerts, comedy, theater, trivia, festivals, community and family events, including events at small venues. Combines semantic search over venue vibes, geographic radius filtering, date/cost/category filters, and audience tags. Returns ranked event facts, stable event_id values, canonical VenuNite event_url links when a stored slug exists, original source_url links for provenance, and applied filters. The legacy url field remains the original source. VenuNite event pages include ticket links when available.
The tool cannot buy tickets, create or modify events, edit calendars, or message organizers. Calls record private quota and request telemetry. An uncached place_name is sent to the public Nominatim geocoder.
Link health never removes an event. When every outside link an event stored is broken, or it stored none, source_url and url are null and ticket_link_status is unavailable or missing; event_url still opens its VenuNite page.
Tag vocabulary is fixed (49 canonical tags across 6 facets: ambiance, social, time, age, venue_type, activity). See the vibe_tags field description.
Safety-critical tags (queer-friendly, family-friendly, all-ages, 18-plus, 21-plus) are hard filters: results that don't satisfy them are excluded entirely, never just down-ranked. family-friendly, all-ages, 18-plus and 21-plus are judged on each event's own audience and age policy, with the venue's tag counting only when the event's classification doesn't contradict it; queer-friendly is a venue tag.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Ordering axis. Results are presented by calendar day in timezone; sort orders within each day. With query_text, the server selects the strongest event-text and venue-vibe matches under every sort, and sort only orders them. Without query_text, the result limit is shared across the days of the window: events starting inside it come before events already under way, and each day contributes its next event on the sort axis. | |
| limit | No | Number of events to return. Default 20. Prefer small (5-10) when the user asked for a single recommendation. | |
| date_end | No | Exclusive ISO-8601 end of the search window, including the local UTC offset. Default: 14 days from date_start. The words now, today, tonight, tomorrow and this weekend are also accepted and resolved in the caller's timezone. 'Tonight' → date_start + 6 hours. 'Next weekend' → date_start + 2 days. An event starting exactly at date_end is outside this window. | |
| max_cost | No | Upper bound on event cost in USD. 'cheap' ≈ 15, 'affordable' ≈ 30, 'under $X' → X. Events with no listed price stay in the results (most events list none), so present their price as unverified rather than excluding them. max_cost=0 returns only proven-free events. Leave unset if the user didn't constrain price. | |
| min_cost | No | Lower bound on event cost. Rarely useful — only set when the user explicitly excluded free events. | |
| timezone | No | IANA timezone (e.g. 'America/New_York') used for the calendar-day grouping of results. Default UTC — pass the user's local zone so 'today/tomorrow' day buckets match their clock. | UTC |
| vibe_tags | No | Canonical vibe vocabulary. Include tags the user explicitly or strongly implied. IMPORTANT: the tags `queer-friendly`, `family-friendly`, `all-ages`, `18-plus`, `21-plus` are HARD filters — only include them when the user's query explicitly asked for that property. Including `family-friendly` for a user who just said 'something fun tonight' will exclude most events. | |
| categories | No | Event category(s). Map the user's intent: 'live music' → music, 'standup' → comedy, 'trivia night' → trivia-games, 'art opening' → arts-culture. 'anything to do' → omit (no category filter). | |
| center_lat | No | Latitude (only if you already have precise coordinates — otherwise pass place_name). | |
| center_lng | No | Longitude (paired with center_lat). | |
| date_match | No | overlap includes events already running during the window, such as multi-day festivals or prior-night shows; events ending exactly at date_start are excluded. starts_within requires the event to start at or after date_start and before date_end. Prefer starts_within for requests about events starting tomorrow, on a specified date, this evening, or this weekend. Keep overlap when the user asks what is currently happening or wants ongoing activities. | overlap |
| date_start | No | Inclusive ISO-8601 start of the search window, including the local UTC offset. Default: now. The words now, today, tonight, tomorrow and this weekend are also accepted and resolved in the caller's timezone. For 'tonight' pass now. For 'this weekend' pass the upcoming Saturday midnight. The timezone field controls day grouping, not parsing: date-times without an offset are interpreted as UTC. Use date_match=starts_within when the user wants events starting on a particular date or evening. | |
| local_only | No | Set true when the user's query implies 'in my immediate area' — 'what's on my block', 'nearby tonight', 'close by'. The server clamps the effective radius to a neighborhood-scale max based on local density (≤10mi urban, ≤30mi suburban, ≤50mi rural), even if radius_miles is larger. Prefer this over guessing a small radius — the server knows the density of the area and you don't. | |
| place_name | No | Human-readable location if the user mentioned one: 'Westminster, CO' or 'Five Points Denver'. Prefer this over guessed lat/lng when you have a name; existing precise coordinates take precedence. Always include the state abbrev when the city name is ambiguous. An unresolved place returns location_unresolved; correct the place or use known coordinates rather than dropping the location. | |
| query_text | No | Free-text vibe description extracted from the user's query. Keep it short — e.g. 'chill jazz' or 'loud rock club'. Omit when the user's request is purely geographic / tag-based (e.g. 'any comedy shows tonight near me'). | |
| state_hint | No | Two-letter state abbreviation to disambiguate place_name (e.g. place_name 'Frederick' + state_hint 'MD'). Unnecessary when place_name already contains the state. | |
| radius_miles | No | Search radius in miles. OMIT this field to let the server pick a density-aware default: 5mi in dense metros (Chicago, NYC), 15mi suburban, 25mi rural. Only pass an explicit value when the user's phrasing implies a specific scope: - 'walking distance' / 'on my block' → 2-3 - 'near me' in a dense downtown or neighborhood → 5-7 - 'near me' in a suburb → 10-15 - 'metro area' / 'anywhere in <city>' → 25-30 - rural 'near me' or 'within driving distance' → 25-50 For a user who says 'things to do tonight' in Lincolnwood, Chicago, or any other dense-urban location: omit this field. Passing 15 there pulls events from 8-10 miles away in other neighborhoods, which is worse than the density-aware default. Range 0.5 to 500. An out-of-range value FAILS the entire call and returns zero events — it is not clamped — so omit the field rather than guessing. Use 'local_only: true' instead of a small radius when you're unsure of local density. | |
| max_events_per_venue | No | Per-venue diversity cap. Default 1 — each venue contributes at most one event, giving a diverse 'what's on' feed. Raise to 3-5 for 'what's on at <specific venue>' queries where the user expects multiple shows from the same room. | |
| include_unknown_prices | No | Include events whose admission price cannot be determined. Default true preserves broad discovery; positive price bounds may then include unknown prices, which must be labeled unverified. false keeps only events with a listed price; most events list none, so it can empty an answer, and 'under $X' alone is not a reason to set it. When it leaves three or fewer results, applied_filters.available_if_relaxed reports how many the same search returns with unknown prices included. This never relaxes the proven-free requirement of max_cost=0. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| results | Yes | ||
| applied_filters | No | ||
| validation_errors | No |