Understanding Responses

Comparison to OpenActive Source Data

The imin responses are compatible with the OpenActive modelling specification, and even pass using the OpenActive validator.

Augmented Fields

The imin search results have additional properties added to them for convenience. For example imin:fullAddress reliably contains the full address, regardless of the components present. All the fields in the response can be found documented in the API Reference.

imin:totalItems

imin:totalItems appears in all Search API calls across the Events, Facilities and Places APIs. It is the number of items that match the search request across all pages and may be an approximation.

When there is a small number of results (e.g. just one page of results), this number will be precisely accurate and reflect the exact number of items that match the search request.

However, this is not the case when there are a larger number of results. The reason for this is that our Platform will make an approximation in order to improve the performance of the search.

If you are communicating imin:totalItems to the end user, please note that it may be an approximation depending on the number of items returned by a search request.

2-week API Lookahead Window

The API will only return information about events that are due to take place within the next 14 days. This is to ensure that the amount of data returned is manageable (by reducing the EventSeries object size) and relevant (our research shows that the bookable window for most leisure operator members is 2 weeks in advance).

Maximum URL Length

Each API call should be limited to a maximum of 2,048 characters.

null Values and Empty Arrays

Across all of our APIs, we will remove any field if:

• The value is null; or

• The array is empty.

This is a general principle set out in the OpenActive Specification here.

Archiving of EventSeries and FacilityUses

We archive ScheduledSessions and Slots that are in the past (startDate < now). If an EventSeries' ScheduledSessions are all archived, the EventSeries will no longer appear in By-ID search routes. This is also the case for a FacilityUse when all its Slots are in the past.

EventSeries/FacilityUse By-ID routes do not persist when all associated ScheduledSessions/Slots are in the past.

Parameters and the Number of Items Returned

The more parameters you add, the more specific you are being about what data you want the Platform to provide and so the less items an API call will return.

• 0 parameters included in an API call = X thousand items^ returned;

• 2 parameters included in an API call = X hundred items^ returned.

• 6 parameters included in an API call = X hundred items^ returned.

^ These numbers are for illustrative purposes only.

Identifying Data Sources

The data our Platform originates from a variety of organisations that publish open data, e.g. Active Northumberland. These organisations, many of which are listed on OpenActive’s Status Page and Supplemental Status Page, can be identified in our API by looking at "imin:dataSource": "identifier", e.g. activenorthumberland.

However, identifier may not necessarily be simply an organisation's name. This is because, over time, feeds can be deprecated and replaced by a newer versions. As a result of this, we can end up with multiple identifiers from the same organisation in our Platform. To distinguish between them, we include the year the new feed is released, e.g. everyoneactive2020.