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"). Slots will be returned and limited to a specific date when a startDate parameter is included in the API query.

Please note that when making a query parameter search, the API will only return slots where startDate[gte] and/or startDate[lte] are included in the query. If neither is included, then only details of the facilities will be returned, i.e. without available times.

Please note that when a startDate query parameter is included, the API will only return slots on the specific date stipulated by either startDate parameter.

For example, the following query, https://search.imin.co/facilities-api/v2/facility-uses?geo%5Bradial%5D=51.719732,-1.198388,1000&mode=discovery-geo&limit=50&page=1&providerId=fusion&activityPrefLabel=Football, will return:

  • Those fusion facilities;

  • Within a 1000km radius of 51.719732,-1.198388;

  • That have the activity Football.

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

The following query, https://search.imin.co/facilities-api/v2/facility-uses?geo%5Bradial%5D=51.719732,-1.198388,100&limit=50&page=1&providerId=fusion&activityPrefLabel=Tennis&startDate[gte]=3000-01-01T16:00:00Z, will return:

  • Those fusion facilities;

  • Within a 100km radius of 51.719732,-1.198388;

  • 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 it 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

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: upcoming-sessions, discovery-geo, discovery-price-asc or discovery-price-desc.

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=fusion
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. An example of this is: https://search.imin.co/facilities-api/v2/facility-uses/fusion-FacilityUse-B5FOOTBALL.

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 Volleyball court): https://search.imin.co/facilities-api/v2/facility-uses/fusion-FacilityUse-LCVOLLEYBALLR.

Query parameters cannot be used to complete a ByID search.