The imin Platform

imin Events API Places Endpoint

Display Data on a Map

We provide a list of all locations matching search parameters at /events-api/v2/places. Within the item:item array in the response are objects such as the following:
"type": "Place",
"geo": {
"type": "GeoCoordinates",
"latitude": 51.497063,
"longitude": -0.221201,
"imin:distanceFromGeoQueryCenter": {
"type": "QuantitativeValue",
"value": 19.002,
"unitCode": "KMT"
"name": "Brook Green Tennis Club",
"address": {
"type": "PostalAddress",
"postalCode": "W6 7BD",
"addressRegion": "Middlesex",
"streetAddress": "Brook Green",
"addressCountry": "GB",
"addressLocality": "LONDON"
"imin:event": {
"type": "imin:RestrictedCollection",
"id": "[radial]=51.497063,-0.221201,0&startDate[lte]=2018-09-17T10:45:59Z&mode=discovery-geo",
"imin:totalItems": 3
The Places endpoint returns Place objects.

Breakdown of the Fields

  • geo: this object contains the coordinates for placing a pin on the map
  • imin:event: this Collection identifies all sessions available at the location
    • id: a URL returning all available EventSeries items at the location
    • imin:totalItems: the number of available EventSeries items at the location
  • imin:distanceFromGeoQueryCenter: provides information on the distance in kilometres from the search coordinates to the location

/events-api/v2/places versus mode=discovery-geo

The Event's API Places endpoint is the best way to put pins on a map.
Using mode=discovery-geo will return events based on distance from the geo[radial] in ascending order. When there is a large number of items returned for one specific location, e.g. at a leisure centre, using mode=discovery-geo to populate the map will show lots of pins at that same location (up to a maximum of 50 on each page based on the API limit of 50).
However, when /events-api/v2/places is used, each location will be listed only once, regardless of the number of events taking place there. By plotting one pin on a map,, a preconstructed API call including a Places latitude and longitude, can be used to allow a user to click on a map pin to show all of the events taking place at that location.
mode=discovery-geo will put numerous pins on a map at one location, which will impact the user experience.
/events-api/v2/places will put one pin per location on a map regardless of the number of events taking place there. This makes the map easier to use for the end user. will return all events taking place at a specific location.

Ways to Attach a URL to a Pin

The URL for returning all sessions at a location is accessible at JSONPath:$['imin:event'].id and can be used in different ways according to your UI preferences. Two suggestions are:
  • Use the URL as a link so that clicking the pin opens a new window displaying your search page with the relevant results.
  • Send an AJAX request to the URL when the user hovers over/clicks on the pin in order to populate a popover with results.
Similarly the number of total sessions could be displayed in a popover by drawing the number from $['imin:event']['imin:totalItems'].