Searching on Eventful can be as simple as What, Where, and When, but sometimes you might want to find something more specific or weed out results that aren't relevant to your application.
The API provides many ways to search through our events, venues, performers, demands, calendar, groups, and users. Some of the most common options are introduced here. Example links to eventful.com are provided in some cases; note that the same search terms can be passed along to the API directly.
What: The 'what' argument, also called 'q' or 'keywords', is used to search by any aspect of an event that isn't part of the category, location or time.
Where: The 'where' argument, also called 'l' or 'location', is used to search by city, region, postal code (ZIP), country, street address, or venue. It's often used in concert with the 'within' and 'units' parameters to do a radius search.
When: The 'when' argument, also called 't', is used to search within a specific time frame. The default is "Future", but many other human-readable time formats are supported, plus keywords like "Past", "This Weekend", "Friday", "Next month", and "Next 30 days".
Category: The 'category' argument, also called 'c', is used to search within a category.
By default, any What search term will be matched against a set of search domains. For example, a "music" search for events will search the title, description, and tags for the term "music". To search against a specific domain, add the domain to each search term, separated by a colon (:).
Most attributes are searchable by domain. Here's a partial list:
In the What argument, search terms are joined with AND by default, which means that each result must match all of the terms. AND or OR can be specified explicitly by using && or || to join the terms. In the Where argument, the entire string is considered a quoted search term unless separated by && or ||.
Why not just use AND and OR, you might ask? We can't reserve OR as a keyword, because it's also an abbreviation for the state of Oregon. (She flies with her own wings, you know.) AND is the abbreviation for Andorra, so it might come in handy someday. We're pretty sure that && and || aren't abbreviations for anything anywhere.
A quoted search term (like "jazz music") can be used wherever a single-word term is used. If specifying a search domain, be sure to put the domain outside of the quotes (like tag:"Kansas City Royals").
Search terms can also be grouped together with parentheses, which is most useful when joining those groups with AND or OR.
It's also possible to narrow a search by excluding results that match a search term.