Search Parameters

Events Manager uses a consistent set of accepted search parameters which you can pass to various shortcodes, template tags, and core functions that search objects like events and locations. For example, when dealing with locations, you should be able to use most general parameters which are also available when dealing with events. Below is a description of specific parameters and general parameters.

Data Type Definitions

When defining the Type of a parameter, we use PHP definitions, and (for you non-coders) can be interpreted as such;

int	A number
bool	true or false, 1 or 0
string	text of some kind, such as "some-text-123"
mixed[]	A PHP array or comma-separated list containing mixed values such as array(1,'value',34) or "1,value,34" A single value can also be supplied, such as 1 or some-value
int[] or string[]	Same as mixed[] but only accepts numbers or strings.

Parameters

General Parameters

These parameters are shared across all shortcodes and template tags that accept parameters. Some default values have different defaults when used in different contexts (e.g. for locations).

For example, [locations_list] will obtain format default values from settings page Formatting > Locations > Location List Formats.

EM_Events::output() would take format from Formatting > Events > Event List Formats

Note

In some contexts these parameters will not make a difference to the returned results.

For example, [event] will accept parameters such as format yet it would not make use of page, given it is not outputting a list.

Parameter	Type	Default	Description
array	bool	0	If you supply this as an argument, the returned data will be in an array, not an object (only useful when using PHP, not shortcodes).
language	string	blog	Show only items in a specific language. Only useful when combined with a supported multilingual plugin. Currently only WPML is officially supported.
limit	bool	0	Limits the amount of values returned to this number. Default value may vary depending on context used.
no_results_msg	string	settings	Text which is displayed in listing functions/shortcodes when there are no results to be shown. Events, locations and taxonomies will have their own default customizable text in the relevant settings page area.
offset	int	0	For example, if you have ten results, if you set this to 5, only the last 5 results will be returned. A limit higher than 0 is required for offsets to work.
pagination	bool	0	When using a function or shortcode that outputs items (e.g. [events_list] for events, [locations_list] for locations), if the number of items supersede the limit of items to show, setting this to 1 will show page links under the list.
page	int	1	Which page shall be shown. Requires pagination to be set to 1 and will override the offset value if also provided.
page_queryvar	string	pno	The parameter name used to figure out the page number in a url, provide a unique name if you want to display two lists on the same page with independent pagination.

Format Parameters

These parameters can be supplied to alter the formatting when used in output functions, such as EM_Events::output() or EM_Locations::output()

Important Changes

As of 6.4.11, these formatting parameters will not be permitted by default with shortcode, for security purposes. We do not recommend using these for shortcode anymore, because you can included these values before, within and after the shortcode.

We have covered this in a specific shortcode security documentation page.

Parameter	Type	Default	Description
format_header	string	settings	If you are displaying lists (e.g. listing events), you can supply the header html and placeholders here.
format	string	settings	If you are displaying some information with the shortcode or function (e.g. listing events), you can supply the html and placeholders here. When providing a custom format value, format_header and format_footer will default to blank if not also provided.
format_footer	string	settings	If you are displaying lists (e.g. listing events), you can supply the footer html and placeholders here. Default value: If the format attribute is not provided, the relevant default format will be taken from the settings page.

General CPT Searches

These parameters are limited to Custom Post Types, or content objects, like Locations and Events, which share similar traits such as publish status, visibility etc.

When searching for locations, the parameter defined here takes precedence for locations. For example, if searching locations by status, locations with the status parameter will be returned, and vice-versa for events.

Parameter	Type	Default	Description
blog	int[]	false	Limit search to events/locations created in a specific blog id or ids. Default Value: Current blog ID being viewed, or if the main blog/site all blog events/locations are shown. info Only works with MultiSite in MultiSite Global Mode
groupby	string	null	Group events by a certain type of data. More Info See our grouping docs for more information and examples.
groupby_orderby	string[]	null	Determine ordering of each set of grouped events when groupby is set.
groupby_order	string	ASC	Indicates the alphabetical/numerical order of the grouped lists defined by groupby. Choose between ASC (ascending) and DESC (descending).
order	string	ASC	Indicates the alphabetical/numerical order of the lists. Choose between ASC (ascending) and DESC (descending).
orderby	string[]	settings	Choose what fields to order your results by. Accepted Arguments: Database table fields, e.g. event_name or location_country,location_town
owner	int[]	0	User ID(s) to filter events/locations owned by user. Supplying me will show events/locations belonging to logged-in user.
post_id	int[]	false	Limit the search to events with the supplied post_id(s).
private	bool	user	1 includes, 0 excludes private events/locations. If undefined, private events/locations are shown to users with capability to view private events/locations.
private_only	bool	0	Show private events/locations only
search	string		Search for events containing provided text within event name, description and location.
status	mixed	publish	Search events with a specific publish status. 1 - Published 0 - Pending -1 - Draft null - Trashed Also accepts : publish, pending, draft, trash, all (exc. trashed), everything (inc. trashed)

Event Parameters

Along with these parameters, you can also use the general parameters and location parameters for filtering by location.

This applies to all event-related functions and shortcodes, e.g. em_events(), [events_list], EM_Events::get()

Parameter	Type	Default	Description
active	bool	null	1 includes or 0 excludes events with an Active status.
active_status	mixed	null	Accepts a single int or commma-seprated list of int event status values. Negative numbers will exclude. 1 - Active 0 - Cancelled tip This setting is useful particularly if you have implemented custom event status types. Otherwise, you could include/exclude active or cancelled events using the active and cancelled paremeters.
bookings	bool	null	1 includes or 0 excludes events with bookings enabled. If "user" is supplied, bookings belonging to the current user will be returned.
cancelled	mixed	settings	1 includes or 0 excludes events with an Cancelled status.
category	mixed[]	0	Category IDs or slugs to include in the list of searchable tags. Prefix the ID or slug with a minus - to exclude that category. Example: -jazz,-rock includes everything except rock and jazz
date_format	string	settings	Date format for headings in a grouped list (defined in mode). Accepts PHP date formatting syntax.
event	int[]	0	Filters list to return only the supplied Event ID(s).
event_location_type	string	0	Event location type, such as url or zoom, not physical locations.
location_status	bool	0	Search events with locations of a specific publish status value.
has_event_location	bool	0	Search events with non-physical locations, such as a URL or Zoom location.
has_location	bool	0	Search events with a physical location
header_format	bool	0	Header format for group of events in a grouped list (defined in mode). Accepts HTML and replaces #s with the date defined by date_format, for example <h2>#s</h2>
location_status	bool	0	Search events with locations of a specific publish status
mode	string	0	Display events in a grouped mode, such as daily,weekly,monthly or yearly
month	int		Month filter, such as 1for January, 12 for December
no_location	bool	0	Search events without a physical location
recurrences	bool	null	1 will only show, 0 will omit events that are part of a recurring pattern, if not set, one-off and recurring events will be shown.
recurrence	int	0	Show a specific set of event recurrences, defined by recurrence_id
recurring	bool	null	1 will show recurring event templates. Important Recurring events are not actual posts/pages for publication, but a template for defining individual recurrences.
scope	string[]	settings	Date or date range for which to search events by. Default value is future or preset by settings depending on context shown. Preset Ranges: future past today, tomorrow, week, this-week, month, this-month, next-month, 1-months, 2-months, 3-months, 6-months, 12-months, all Date Ranges: yyyy-mm-dd,yyyy-mm-dd Searches between these two dates. yyyy-mm-dd, Searches from the start date onwards. Single Dates yyyy-mm-dd Searches a specific date. tip You can create your own event scope and use it here as well!
tag	int	0	Category IDs or slugs to include in the list of searchable tags. Prefix the ID or slug with a minus - to exclude that category. Example: -jazz,-rock includes everything except rock and jazz
timezone	string[]	false	Events in one or more timezones, for example: Europe\Londonor Europe\London,Europe\Madrid. Defaults to the current blog timezone.
year	int	today	Filters events during defined year, defaults to current year, such as 2024.

Location Parameters

Along with these parameters, you can also use the general parameters and event parameters for filtering locations according to events.

This applies to all location-related functions and shortcodes, e.g. em_locations(), [locations_map], EM_Locations::get()

Important - Geographical Searches

All geographical parameters such as country,town,state,region and postcode accept comma-delimited or a PHP array of searchable values.

Additionally, you can supply negative values (using a minus - sign before a value) to exclude items from returned results. For example:

state="NY,FL" - Searches New York and Florida country="-DE,-GB" - Searches all countries except Germany and United Kingdom

If you mixed positive/negative values in the same search, negatives are ignored, for example;

country="DE,-GB" - Searches locations in Germany only.

Aside from country, which is stored in ISO 3166-1 alpha-2 format, these values are searched as stored in the database, so if you use abbreviations for states, like NY for New York, search for NY

Parameter	Type	Default	Description
country	string[]	false	Filter by locations in supplied country(ies) using ISO 3166-1 alpha-2 format. Accepts country codes like US,DE or full names as per blog language, such as Spain in an English site. Additionally accepts negative exclusions, so for example -DE,-GB will show all locations not in Germany and United Kingdom. More Info See our geographical search notes above for more info.
event_status	bool	0	Search locations with events of a specific publish status value.
eventful	bool	0	Locations that have an event associated with it.
eventless	bool	0	Locations without events, eventful takes precedence.
location	int[]	0	Filter by location with the supplied Location ID(s).
near	float[]	0	Latitude, longitude coordinates, supplied like so: 123.123,321.321
near_distance	int	settings	Numerical distance from near coordinates, the unit type (kilometers or miles) is defined by near_unit
near_unit	mixed	settings	Distance unit (mi or km) defined by near_distance
postcode	string[]	false	Search locations with or without the supplied postcode(s) More Info See our geographical search notes above for more info.
region	string[]	false	Search locations in or not in the supplied region(s) More Info See our geographical search notes above for more info.
state	string[]	false	Search locations in or not in the supplied state(s) More Info See our geographical search notes above for more info.
town	string[]	false	Search locations in or not in the supplied towns/cities. More Info See our geographical search notes above for more info.

Category/Tag Parameters

Aside from general parameters for lists, see the WordPress get_terms() Codex for a list of possible search parameters/arguments.

These would be used in shortcodes such as [categories_list], [tags_list] or PHP functions like EM_Categories::get()

Calendar Parameters

Calendar searches are generally used for display purposes, and most of the arguments specific to calendars surround intentions of display. This applies to all calendar-related functions and shortcodes, e.g. em_calendar(), [events_calendar], EM_Calendar::output().

Some of these search parameters may come in handy in advanced usages too, such as EM_Calendar::get() which returns the array of data used to populate a calendar.

Along with these parameters, you can also use the general, event, and location parameters to refine the displayed events on a calendar.

info

There are certain parameters below already described in other sections, however they behave differently for calendars and detailed here.

Parameter	Type	Default	Description
calendar_size	string	auto	Displays calendar in a fixed size if provided a value of large, medium or small, if not defined the calendar will be responsive.
has_search	bool	1	Displays a search form trigger button, which opens up an advanced search modal. Use show_search to display a search form above the calendar.
show_search	bool	0	If has_search is enabled, the search form will be displayed above the calendar, respecting default search form settings unless overriden by search form parameters.
calendar_event_style	string	pill	Choose what style to apply to your event dates, default is pill, this is the only currently supported value. You can also add a custom value to add a css class to your calendar instead of event-style-pill and take over with custom CSS.
calendar_dates_height	string	apsect	Control how rows of dates on the calendar grid auto-adjust height based on content within the whole calendar. Accepted Values even - height of each row will adjust to match tallest cell/row in entire table. aspect - height will match width of cell, unless there is more content and then that row will match tallest cell. auto - no restriction, each cell in a row will adjust height to tallest cell in that row.
calendar_preview_mode	string	modal	Determines how events are previewed when clicking on a specific event in a calendar. Accepted values are modaland tooltips
calendar_preview_mode_date	string	modal	Eventful dates will display a modal by default with the list of events, if set to none clicking on a date will go straight to event date page with a list of events.
calendar_nav	bool	true	Displays the navigation elements at the header of the calendar, including month picker, next/previous month and today links.
calendar_month_nav	bool	true	Displays the month picker at the header of the calendar. Requires calendar_nav to also be true.
calendar_nav_nofollow	bool	true	Adds rel="nofollow" to the calendar navigation links to prevent unnecessary search engine indexing.
limit	int	settings	Number of events to return per date, rather than total number of events returned.
long_events	bool	1	Displays events that span more than one day on each calendar cell where it's active if set to 1.
month	string		Choose the starting month being displayed on page load, default is today's month, or the first date defined in scope
number_of_weeks	int	auto	Number of weeks to return, if not defined, determined by the month and number of days in the month, this is usually 5or 6 to allow the weekdays before and after the current month being displayed.
scope	string		Different to the regular scope argument, it only accepts a comma-separated set of dates, or future. future will default to display the current month with events starting from today.
year	string		Same as month but for the year.
full	bool	false	Shortcut for calendar_size = "large" if set to true, this paremeter is not recommended anymore and documented for posterity, use calendar_size instead.

Booking Parameters

Booking parameters can be provided specifically to booking PHP functions, such as EM_Bookings::get(). There are no shortcodes that expose these parameters due to privacy/security reasons.

Parameter	Type	Default	Description
array	mixed	0	If you supply this as 1, the returned data will be in an array, not an object (only useful when using PHP, not shortcodes) note You can also supply an array of column names from the wp_em_events and wp_em_bookings table to return back, such as booking_id, event_name etc.
owner	int	conditional	Search by person's bookings warning Use with caution, as this can expose confidential data. If not defined, the owner will default to the currently logged in user if the user cannot edit other user events.
person	int	0	Search for bookings belongs to a specific person with their WordPress User ID.
rsvp_status	int	0	Filter by RSVP status of booking, accepts the following values: Accepted Values 0 - Not Confirmed 1 - Confirmed 2 - Not Attending
status	int	0	Status of booking, such as confirmed or pending payment. Accepted Values 0 - Pending 1 - Confirmed 2 - Rejected 3 - Cancelled 4 - Awaiting Online Payment 5 - Awaiting Offline Payment 6 - Waitlisted
ticket_id	int	0	Filter bookings containing this ticket ID

Examples

This is a shortcode showing a paged list of 10 events that occur tomorrow:

[events_list scope=’tomorrow’ limit=10 pagination=1 ][/events_list]

This is the equivalent using PHP:

echo EM_Events::output(array(‘scope’=>’tomorrow’, ‘limit’=>10, ‘pagination’=>1));

This is a list of locations that have events located in the US tomorrow:

[locations_list scope=’tomorrow’ limit=10 pagination=1 eventful=1 country=’US’][/locations_list]

This is the equivalent using PHP:

echo EM_Locations::output(array(‘scope’=>’tomorrow’, ‘limit’=>10, ‘pagination’=>1, ‘country’=>’US’, ‘eventful’=>1));