Search Local Events
search_eventsFind events matching a user's natural-language request. Combines semantic search over venue vibes, geographic radius filtering, date/cost/category hard filters, and strict safety 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 the filters that shaped the results. The legacy url field remains the original source. Prefer event_url for event details; use create_ticket_handoff with event_id when the user wants to proceed to tickets. Call this ONCE per user query with the structured args you inferred from their question — do not try to issue multiple speculative calls.
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.
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. Only include a safety tag when the user's query explicitly requested it.
Input 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 and no explicit sort (or relevance), the server selects the strongest event-text and venue-vibe matches before applying that day order. Explicit date, distance, or demand sorts select by day and that axis. Without query_text, default date is chronological. | |
| 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. '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. Set include_unknown_prices=false when the user explicitly wants a verified budget such as 'under $100'. 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. | |
| 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. 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. Set false with min_cost/max_cost when the user explicitly requires a verified budget. This never relaxes the proven-free requirement of max_cost=0. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| results | Yes | ||
| applied_filters | No | ||
| validation_errors | No |