How to display data on a map

The Events API’s Places Endpoint

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": "https://search-sandbox.imin.co/events-api/v2/event-series?geo[radial]=51.497063,-0.221201,0&startDate[lte]=2018-09-17T10:45:59Z&mode=discovery-geo",
    "imin:totalItems": 3
  }
}

Note

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

Tip

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, imin:event.id, 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.

Caution

mode=discovery-geo will put numerous pins on a map at one location, which will impact the user experience.

Tip

/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.

imin:event.id 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'].