Discovery
What the public search shows, which filters and sorts exist, and why an Event is missing from results
Discovery is the public search across every Organization's Events. Nothing to configure: an Event is either eligible or it is not.
Results read the operational tables directly, so they reflect an Event's current state rather than a copy that can drift.
What is eligible
Four conditions must all hold.
| Condition | Value |
|---|---|
| Publication | published |
| Visibility | public |
| Moderation | active |
| Schedule | scheduled or postponed |
Everything else is absent from results, and most of it is absent without an error.
| State | In search? | Why |
|---|---|---|
| Draft, private, unlisted | No | Not public |
| Archived, cancelled, completed | No | Nothing left to buy |
| Suspended or banned | No | Moderation gate |
| Postponed | Yes | Still happening, just later |
Postponed is included on purpose: the Event still happens, so it stays findable with its notice attached.
Filters
| Filter | Accepts | Notes |
|---|---|---|
q | Free text | Name, summary, venue, city, category, topic names |
category | One catalogue slug | The format axis |
topics | One or more slugs | Matches any of them |
mode | in_person, online, hybrid | Exact participation mode |
online | true or false | True includes hybrid; false excludes online |
dateFrom | RFC 3339 | Keeps Events ending at or after this moment |
dateTo | RFC 3339 | Keeps Events starting at or before this moment |
cityId | Gazetteer city ID | Exact city |
cityName | City name | Case-insensitive match |
venueId | Venue ID | One venue |
price | free or paid | Based on active Passes |
seriesId | EventSeries ID | Member Events of one series |
near | lat,lng | Origin for distance |
radiusKm | 0 to 500 | Requires near |
bbox | minLng,minLat,maxLng,maxLat | Map viewport |
The date pair overlaps rather than contains: an Event that started yesterday and runs today still matches dateFrom today.
Price is about the offer. An Event with one free and one paid Pass matches both free and paid.
Topics match any, not all: music, food returns Events tagged with either.
Sorts
| Sort | Default when | Order |
|---|---|---|
date | No query and no origin | Earliest start first |
relevance | A query is present, with or without an origin | Full-text rank, highest first |
distance | No query, and an origin is present | Nearest first |
Two combinations are rejected with a 400: relevance without a query, and distance without an origin.
Text search covers name, summary, venue, city, category, and topic names. Alongside that it runs a plain substring match on the Event name, the venue name, and topic names, so a partial word still finds something.
Queries are parsed as web-search syntax, so or and quoted phrases work.
Pagination
Results page 20 at a time, up to 100. Each page carries a cursor bound to its filter.
Changing a filter mid-scroll invalidates the cursor, and the API returns an invalid-cursor error instead of mixing two result sets.
There is no offset parameter, so a page stays stable when an Event is published between requests.
Date searches page cleanly. Distance can repeat the boundary card, because the cursor stores the distance rounded to three decimals. Relevance is worse: the cursor loses the rank, so a second page returns an incomplete set instead of the next slice.
Use date when a query has more matches than one page.
What a result carries
A card renders from one call.
| Field | Notes |
|---|---|
| Identity | ID, slug, name, summary |
| Organizer | Organization display name |
| Schedule | Start and end instants, timezone |
| Place | City, region, country, precision |
| Distance | Present only for distance searches |
| Price | Mode, lowest price, optional strike-through price, currency |
| Artwork | Cover and poster URLs |
| Style | The Event's presentation selection |
| Collections | Owning series or group, only when published and non-private |
| Paused flag | True when sales are paused |
Price follows the cheapest active Pass, with a strike-through when an active Pass carries a higher list price. An Event with no active Pass reports mode none, not "free".
A series or group is attached only when it is published, non-private, and owned by the same Organization, so private collections never leak.
Location follows the exact-venue setting: off drops the venue name and address and rounds coordinates to two decimals.
City facets
The popular-cities endpoint returns up to 50 cities with their eligible Event counts, ordered by count then name. It uses the same rules as search, so a city with only private or cancelled Events drops off.
A worked example
A buyer types "music", picks Bengaluru, and filters to free.
The API receives q=music&cityName=Bengaluru&price=free, sorts by relevance, and returns 20 matches, each with its price, organizer, and rounded map point.
Priya's unlisted sound-check does not appear though it matches every term. Her public festival does: published, public, active, scheduled, with a free Pass.
Related
- Visibility — the switches that decide eligibility
- Event Groups and Series — the collections attached to results
- Publishing — how an Event becomes eligible
- Event visibility — the reference matrix