Query Parameter Search

Mandatory Query Parameters

The mandatory query parameters that must be present in all API searches are:

geo[radial]
mode

geo-[radial]

Tip

geo[radial] must take the form lat,lng,radiuswhere radius is in kilometres. For example, geo[radial]=51.5081,0.1248,5.

mode must utilise one of the following: discovery-geoor upcoming-slots.

mode

mode=discovery-geo

When using mode=discovery-geo, the startDate[gte] and startDate[lte] parameters are not permitted. As a result of this, the API will return details of the facilities, but will not include the slots available.

Danger

For the avoidance of doubt, just because no slots are returned when mode=discovery-geo is used does not mean there are no slots available. Available slots will only be returned when mode=upcoming-slotsis used.

When using this mode, the facilities returned will be ordered by distance to the geo[radial] supplied, with closest first. For example, the query, https://search.imin.co/facilities-api/v2/facility-uses?geo[radial]=51.05602333,-2.423247080,100&mode=discovery-geo&limit=50&page=1&providerId=led&activityPrefLabel=Tennis, will return:

• Those led facilities;
• Within a 100km radius of 51.05602333,-2.423247080;
• That have the activity Tennis.

Note

In the future we may offer other modes, such as discovery-price-asc and discovery-price-desc , much like our Search API.

mode=upcoming-slots

The only permitted mode with which either startDate[lte] or startDate[gte] can be supplied mode=upcoming-slots. The results returned will contain time-based information pertaining to one specific day and be ordered chronologically.

Caution

When one of startDate[lte] or startDate[gte] is used, slots will only be returned for the calendar day specified in that parameter.

Danger

startDate[lte] and startDate[gte], when used in combination, can only span one calendar day.

For example, the query, https://search.imin.co/facilities-api/v2/facility-uses?geo[radial]=51.05602333,-2.423247080,100&mode=upcoming-slots&limit=50&page=1&providerId=led&activityPrefLabel=Tennis&startDate[gte]=3000-01-01T16:00:00Z, would return:

• Thoseled facilities;
• Within a 100km radius of 51.05602333,-2.423247080;
• That have the activity Tennis; and
• All available slots between 16:00-23:59 on 3000-01-01.

Danger

The example query above will not generate any results. This is because the startDate provided is outside of the Platform’s 2-week API lookahead window.

Caution

The functionality of the startDate parameter for the Facilities API is different to that of the Events API. In the Events API, startDate[gte]=3000-01-01T09:00:00Z will return items from 09:00:00 on 3000-01-01 onwards (up until the end of the platform’s 2-week lookahead window). However, in the Facilities API, inclusion of the same startDate[gte] will return slots from 09:00:00-23:59:59 on3000-01-01only.

Note also that an Events API query can include startDate[gte]and startDate]lte]for different dates, e.g. startDate[gte]=3000-01-01T09:00:00Z&startDate[lte]=3000-01-05T18:00:00Z. The Events API will return events from 09:00:00 on 3000-01-01 until 18:00:00 on 3000-01-05 . It is not possible to include two different dates when using the Facilities API.

The API will return a list of multiple facility uses (e.g. volleyball courts, football pitches, etc.) without slots for the next 2-weeks when making a query parameter search that does not include a startDate.

Note

It is not possible to return slots using a query parameter search that does not include a startDate due to the large quantity of data involved in such an API call, i.e. multiple facilities + multiple days + no slots.

You can use the startDate parameter with a query parameter search to return slots for multiple facilities on a specific day, i.e. multiple facilities + one day + slots. Alternatively, you can use the ByID search (see next page) to return slots for one facility over multiple days, i.e. one facility + multiple days + slots.

mode and Slots

Tip

Regarding provision of slots via the API when using the query parameter search, there are two options available:

i) mode=discovery-geo excluding startDate: multiple facilities + multiple days + no slots.

ii) mode=upcoming-slots including startDate: multiple facilities + one day + slots.

Optional Query Parameters

The following parameters are available for the query parameter search.

Note

We will very shortly provide Swagger documentation, much like those for the Events API found here.

accessibilitySupportId*
activityConceptCollectionId*
activityId
activityInScheme
activityPrefLabel
amenityFeatureType[valueTrue]
availableChannelAdult
availableChannelJunior
limit
membershipRequiredAdult
membershipRequiredJunior
page
priceAdult[gte]
priceAdult[lte]
providerId
startDate[gte]
startDate[lte]

Note

* Please note that the following two optional query parameters are not currently functional given the current data within the Facilities API:

accessibilitySupportId
activityConceptCollectionId

Optional Query Parameters Examples

activityId=https%3A%2F%2Fopenactive.io%2Factivity-list%230a5f732d-e806-4e51-ad40-0a7de0239c8c
activityInScheme=https%3A%2F%2Fopenactive.io%2Factivity-list
activityPrefLabel=Football
amenityFeatureType[valueTrue]=showers
availableChannelAdult=OpenBookingPrepayment
availableChannelJunior=OpenBookingPrepayment
limit=10
membershipRequiredAdult=true
membershipRequiredJunior=false
page=2
priceAdult[gte]=10
priceAdult[lte]=5
providerId=led
startDate[gte]=3000-01-01T09:00:00Z
startDate[lte]=3999-12-31T18:00:00Z

Facets Endpoint

The Facets Endpoint can be found at https://search.imin.co/facilities-api/v2/facets - NB there is a known issue with the Facets Endpoint. It provides an overview of some of the query parameter values that can be used for facilities search, as well as their result count.