Tutorial: Search

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.

The basics

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.

Search domains

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:

matches words in the event title.
matches words in the event description.
matches any tag. For instance, tag:music will find events with the Music tag, but not the "musical" or "Rock Music" tag.
matches the owner of the event (venue, etc), usually the user who created the event. For instance, owner:chris_radcliff will find events owned by the user chris_radcliff.
matches any user marked as "I'm going" to the event. For instance, going:chris_radcliff will find events attended by the user chris_radcliff.
matches a user-defined property/value combination. For instance, prop_name_value:agelimit=21 will find events with the 'agelimit' property set to '21'. (See /events/properties/add for more information about properties.)

AND and OR

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.

Grouping and quoting

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.

Excluding search terms

It's also possible to narrow a search by excluding results that match a search term.