imin Places API [BETA]

Introduction to the Places API

We have been working on a new platform feature called the Places API, which will work in conjunction with and complement the Facilities API.

The Facilities API is designed to deliver a list of all the individual facilities available across a number of places, which means there can potentially be a lot of results presented to the user depending on the search parameters they have entered.

Now, the Places API will allow users to easily see a list of places (e.g. leisure centres near them) and what activities are available at each place. This will enable users to more easily find out what activities they can do at a place, before narrowing down their search using the Facilities API. Their search can be narrowed by things factors like date, time and type facilities, e.g. indoor or outdoor courts.

The data in our Places API is not ever derived from the Events API.

How it works for the user

Let’s say a user wants to search for football in London. If this search were to be powered using the Facilities API alone, the user would be presented with results like:

• 11-a-side - Camden Leisure Centre

• 5-a-side - Camden Leisure Centre

• Whole pitch - Camden Leisure Centre

• 11-a-side - Kings Cross Leisure Centre

• 5-a-side - Kings Cross Leisure Centre

• Half pitch - Euston Leisure Centre

Each of these listings would be a separate result, i.e. they would be presented with a list of all available facilities across a number of locations.

As more data becomes available via our platform - more facilities across more locations - our Facilities API will return increasing amounts of data.

However, if the search results were to be powered initially by the Places API, the user would see results arranged by place:

• Football available at Camden Leisure Centre

• Football available at Kings Cross Leisure Centre

• Football available at Euston Leisure Centre

From here, the user is able to make an easier decision based on the most suitable location(s) for them, see what facilities are available, and find out more specific information about the place as they so please.

After this, the Facilities API can be used to allow the user to select a facility based on type (e.g. indoor, outdoor, etc. using our FacilityUses endpoint) and available times (using our Slots endpoint). Booking will also be possible (where available) via the Facilities API.

Once the Places API call has been made and a facility selected, the geo[radial] in the Facilities API call will need to include the lat/lng for the desired facility found in the Places API search results and a small search radius, e.g. 51.242,-0.729,0.1.

Therefore, the benefits of the Places API will be realised with scale as it will allow users to quickly and easily search across many locations, before using the Facilities API to show more granular information about specific facility availability.

In this way, the Facilities API lends itself to use within a timetable, through which it is easy to display large amounts of slot data concisely and intuitively.

Please note that the imin:aggregatedActivity is not based on the slots information in the Facilities API. As such, the Places API does not offer a notion of availability, but instead only information about a site's ability to host an activity. For example, if a site has badminton courts, but no available slots, it would still be in the imin:aggregatedActivity array in the Places API.

In order to establish whether slots are available for an imin:aggregatedActivity at a specific site, the Facilities API will need to be queried.

Which API to use and when

When to use the Places API:

• When searching for places that have a facilities listed by activity, e.g. tennis, available.

This will not tell you when specific courts are available; just that there is some sort of tennis facility available at that place.

When not to use the Places API:

• When looking for facilities on a specific day.

When to use the Facilities API:

• When searching for multiple facilities on multiple days, but without specific slots; or

• When searching for multiple facilities on a specific day with specific slots; or

• When searching for one facility on multiple days with slots; or

• When searching for one facility on one day with one slot.