Modes

The Events API facilitates the sorting and grouping of results for a number of use cases. We advise you choose your mode based on your use case. Which mode is applied to your results is determined by the value of the mode query parameter. The different modes are detailed below.

Possible Modes

mode=upcoming-sessions

• EventSeries grouping: One-to-One
• Sorting: Results are sorted from earliest to latest startDate. Since only EventSeries items from the future are returned, this means that the first item in the results will always be the very first one that is happening in the immediate future.

• ✅ Supports HighFrequencySessions.

Use a search like /events-api/v2/event-series?mode=upcoming-sessions&iminTag=HighFrequencySession&geo[radial]=51.5,-0.2,10 to power a timetable of High Frequency sessions (e.g. swim and gym)

Because mode=upcoming-sessions uses a One-to-One EventSeries grouping, it will generally return more results than the other modes, which use One-to-Many EventSeries grouping.

• mode=upcoming-sessions -> expect more results to be returned.

• mode=discovery-geo -> expect less results to be returned.

mode=discovery-geo

• EventSeries grouping: One-to-Many
• Sorting: Results are sorted from nearest to farthest from the location specified in the geo[radial] part of the query. So, with path /events-api/v2/event-series?mode=discovery-geo&geo[radial]=51.5,-0.2,10, the first item in the results would be the one which is located closest to latitude: 51.5, longitude: -0.2.

• ❌ Does not support HighFrequencySessions.

Using mode=discovery-geo will not return sessions that are tagged as HighFrequencySessions.

mode=discovery-price-asc

• EventSeries grouping: One-to-Many
• Sorting: Results are sorted from cheapest to most expensive based on the value of JSONPath: $['imin:aggregateOffer'].publicAdult.price.

• ❌ Does not support HighFrequencySessions.

Using mode=discovery-price-asc will not return sessions that are tagged as HighFrequencySessions.

mode=discovery-price-desc

• EventSeries grouping: One-to-Many
• Sorting: Results are sorted from most expensive to cheapest based on the value of JSONPath: $['imin:aggregateOffer'].publicAdult.price.

• ❌ Does not support HighFrequencySessions.

Using mode=discovery-price-desc will not return sessions that are tagged as HighFrequencySessions.