imin Facilities API

Searching the Facilities API

There are two ways to search the Facilities API (search.imin.co/facilities-api/v2/facility-uses/):

  1. Using the query parameter search; or

  2. Using the ByID search.

Query Parameter Search

This endpoint will tell you what facilities are available around you and when (we will refer to the "when" as "slots").

Mode

discovery-geo

When the mode is discovery-geo, the startDate[gte] and startDate[lte] parameters are not permitted. Therefore, the API will only return details of facilities without available times. The facilities returned will be ordered by distance to location supplied, 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.

The example query above will not return the slots available for this facility use as the startDate query parameters are not permitted for this mode.

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

upcoming-slots

When either startDate[lte] or startDate[gte] are supplied, the only permitted mode is upcoming-slots. The results returned will contain time-based information and be ordered by start date closest to now.

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

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.

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.

The functionality of the startDate parameter for the Facilities API is different to 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.

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. 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 below) to return slots for one facility over multiple days, i.e. one facility + multiple days + slots.

Available Query Parameters

The following parameters are available for the query parameter search.

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

Required Query Parameters

geo[radial]
mode

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-geo, upcoming-slots

Optional Query Parameters

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

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

accessibilitySupportId
activityConceptCollectionId

Facets Endpoint

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

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

Regarding provision of slots via the API, there are three options available:

i) Query parameter search excluding startDate: multiple facilities + multiple days + no slots.

ii) Query parameter search including startDate: multiple facilities + one day + slots.

iii) ByID search (see below) to return slots for one facility over multiple days: one facility + multiple days + slots.

ByID Search

Once a query parameter search has been completed, the data returned will include id an for a specific facility use. This is a URL that should be used to return the next 7-days of slots for that specific facility use.

The recommended use for the ByID endpoint is in a timetable view. In terms of the user journey, this endpoint is used when a person has found a facility they wish to use (via a Query Parameter search) and now want to check slot availability over the next week.

For example, the following ByID search will return all slots over the next week for a specific facility use (a badminton courts in a sports hall): https://search.imin.co/facilities-api/v2/facility-uses/led-FacilityUse-W1032A.

Query parameters cannot be used to complete a ByID search.