Skip to content
imin imin Developer Docs

Modes

The Events API facilitates 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 parameter supplied in the URL. The different modes are detailed below.

One-to-One EventSeries

One-to-One EventSeries are described in the Event Series guide. Briefly, these are EventSeries items which have just one individual location, which has just one individual occurrence rather than multiple locations with multiple occurrences. The below sort modes return One-to-One EventSeries items only. One-to-Many EventSeries items are still returned, but they are split into One-to-One items for each location and occurrence.

Sorting results by start date

  • Value for sort: upcoming-sessions
  • Example path: /events-api/v2/event-series?mode=upcoming-sessions&geo[radial]=51.5,-0.2,10

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.

This sort mode only returns One-to-One items as it would not be possible to have a reasonable sorting method that sorts items by start date when each item can have multiple disparate start dates.

One-to-Many EventSeries

One-to-Many EventSeries are described in the Event Series guide. Briefly, these are EventSeries items which can have one or more locations, each of which can have one or more occurrences. The below sort modes return One-to-Many items.

Sorting results by distance

  • Mode: discovery-geo
  • Example URL: /events-api/v2/event-series?mode=discovery-geo&geo[radial]=51.5,-0.2,10

Results are sorted from nearest to farthest from the location specified in the geo[radial] part of the query. So, in the above example, the first item in the results would be the one which is located closest to latitude: 51.5, longitude: -0.2.

Sorting results by ascending price

  • Value for sort: discovery-price-asc
  • Example URL: /events-api/v2/event-series?mode=discovery-price-asc&geo[radial]=51.5,-0.2,10

Results are sorted from cheapest to most expensive based on the value of JSONPath: $['imin:aggregateOffer'].publicAdult.price.

Sorting results by descending price

  • Value for sort: discovery-price-desc
  • Example URL: /events-api/v2/event-series?mode=discovery-price-desc&geo[radial]=51.5,-0.2,10

Results are sorted from most expensive to cheapest based on the value of JSONPath: $['imin:aggregateOffer'].publicAdult.price.