List upcoming events
list_upcomingRead-onlyIdempotent
Browse the next N days of events day by day, with no search words. by_day counts every match per date, and when more events match than limit the rows are spread evenly across the days (earliest first within each day), so each day is represented. Use it for overviews like "what's happening this week"; for search words, free-only, a town or exact from/to dates use search_events, and for one event's details get_event. Optional filters: one category or topic, an audience, and a place: neighborhood keeps events inside a named area (radius_km widens it past the boundary), near ranks events by distance from a place or "lat,lon" within radius_km. No sign-in; each client gets 30 calls a minute and 2,500 event rows an hour.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window in days (default 7, max 60) | |
| near | No | Events within radius_km of a place: a neighborhood, a town, a venue name, or "lat,lon". Results get distance_km, nearest first within each day. Use this for "near X"; use neighborhood for "in X". Unmapped venues are left out (counted in place.unplaced_events). | |
| limit | No | Max rows (default 50, max 100) | |
| topic | No | ||
| sector | No | Industry a work event is for (only events with a work topic carry one; general networking has none): e.g. senior_care, healthcare, real_estate, finance_insurance, legal, tech | |
| audience | No | Who the event is only for: kids, teens, seniors (older adults: senior-center programs, 55+ groups), or general (none of those). Default: no filter. Caregiver/aging talks for families and professionals are general. | |
| category | No | ||
| radius_km | No | Distance for near (default 1.5, max 50), or how far neighborhood reaches past its boundary (default 0) | |
| biz_format | No | Kind of work event: referral_group (BNI etc.), chamber, mixer, breakfast_lunch, workshop_training, conference_expo, career_fair, ce_credits, pitch_demo, committee_meeting | |
| neighborhood | No | Only events in this San Francisco neighborhood (or town): Bayview, Bernal Heights, Castro, Chinatown, Excelsior, FiDi / South Beach, Glen Park, Golden Gate Park, Haight, Hayes Valley, Ingleside / Oceanview, Inner Richmond, Inner Sunset, Japantown, Lakeshore, Lincoln Park, Lone Mountain / USF, Marina, McLaren Park, Mission, Mission Bay, Nob Hill, Noe Valley, North Beach, Outer Mission, Outer Richmond, Pacific Heights, Portola, Potrero Hill, Presidio, Presidio Heights, Russian Hill, Seacliff, SoMa, Sunset / Parkside, Tenderloin, Treasure Island, Twin Peaks, Visitacion Valley, West of Twin Peaks, Western Addition. Sub-neighborhood and common names work too. Add radius_km to also take events within that distance of its centre. Events whose venue isn't mapped can't be placed and are left out; the response's place.unplaced_events counts them. | |
| changed_since | No | Only events added or changed (title, date or time, venue, link, price, sold out, status) at or after this moment: YYYY-MM-DD (local) or an ISO date-time. To follow up later, pass the previous result's changes.synced_at; changes.removed then lists events taken down since. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| count | Yes | Events that matched in total | |
| place | No | ||
| shown | Yes | Events returned (at most limit) | |
| by_day | No | Matches per date (YYYY-MM-DD), all of them, not just the rows shown | |
| events | Yes | ||
| changes | No | Only with changed_since | |
| coverage | No | Coverage and accuracy page | |
| attribution | No | ||
| briefing_url | No | The dated weekly briefing for this week or next (counts plus picks per kind of event, #lane when the filters match one); null further out. Cite it for "what's on this week" | |
| data_generated | No | When this city's data was last published |