Work with maps

The accesso Guest Experience platform's Maps APIs allow you to consume platform content about venue maps.

Venues and maps

Venues each have a collection of maps, each of which can have multiple versions. Only one version of one map can be active at a time, but the Guest Experience platform allows for multiple maps to be defined in order to facilitate changing maps from time to time. Using our Maps API, clients can retrieve metadata about the available maps, retrieve the active version of a map by its ID, and retrieve any version of any map given the map and version ID.

Authenticating

accesso’s APIs rely on access tokens for authenticating. Tokens require an API key and are obtained through a call to the Tokens API. Please contact your assigned Client Engagement Manager for an API key.

Retrieving map metadata

In order to identify the available maps for a venue, you will need the venue ID. The venue ID is a logical identifier for a venue such as a theme park. The venue IDs configured in the platform are available through our venue list API. To identify available venues, execute the following API call:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

curl -X GET \
    https://api.{region}.te2.io/api/v1/public/venues \
    -H 'Authorization: Bearer {token}'

[
  {
    "venueName": "Venue 1",
    "id": "CUST_VENUE1"
  },
  {
    "venueName": "Venue 2",
    "id": "CUST_VENUE2"
  }
]

The response contains an array of JSON objects, each with the following attributes:

Using the venue ID, you can then obtain the map metadata for a specific venue:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

curl -X GET \
    https://api.{region}.te2.io/api/v1/public/venues/{venueId}/maps \
    -H 'Authorization: Bearer {token}'

[
  {
    "mapId": "0",
    "order": 0,
    "title": "Venue 1 Map",
    "versions": [
      {
        "version": 1,
        "description": "Temp map to bootstrap the venue",
        "published": "2019-03-22T14:22:25.594+0000",
        "active": false
      },
      {
        "version": 2,
        "description": "Base map to build real map of the venue",
        "published": "2019-03-22T14:22:24.823+0000",
        "active": false
      },
      {
        "version": 3,
        "description": "Custom Map",
        "published": "2019-03-22T14:22:23.459+0000",
        "active": true
      }
    ],
    "default": true
  }
]

The response consists of an array of JSON objects, each with the following attributes:

Retrieving a map

You can retrieve a map by using its ID, with or without its version number. Use the following API call:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

curl -X GET \
    https://api.{region}.te2.io/api/v1/public/venues/{venueId}/maps/{mapId} \
    -H 'Authorization: Bearer {token}'

{
  "entrance": {
    "position": {
      "x": 0.46438835189837846,
      "y": 0.5311605504575709
    },
    "location": {
      "lat": 37.83808943587798,
      "lon": -77.44391441345215
    },
    "mapId": "0",
    "derivedByOverride": false
  },
  "localLinearTransformStrategy": {
    "label": "LocalLinearTransformPositionStrategy",
    "params": {
      "positionMarkers": [
        {
          "label": "Flight of fear",
          "id": "hwQXu4",
          "latLon": {
            "lat": 37.83917398089429,
            "lon": -77.4387538433075
          },
          "position": {
            "x": 0.75125,
            "y": 0.48829787234042554
          }
        },
        {
          "label": "Dino Alive",
          "id": "3VvJRI",
          "latLon": {
            "lat": 37.8354881574524,
            "lon": -77.4440860748291
          },
          "position": {
            "x": 0.46067415730337075,
            "y": 0.8351661486971074
          }
        }
      ]
    }
  },
  "image": {
    "height": 1880,
    "width": 2550,
    "resolution": "XHDPI",
    "src": "https://d3gy0bjks2buyz.cloudfront.net/CUST_VENUE1/maps/Customer-VenueMap-v4.jpg"
  },
  "mapGrid": [ [  99, ...], [ 99, ...], ... ],
  "order": 0,
  "stepsPerMin": 16
}

The response is a JSON object, including the following attributes:

Transformation between location and position

Our platform provides the ability for a map image to be configured with a non-uniform scale that affects how positions on the map correlate to geographical locations (represented by latitude/longitude pairs). We also provide API support for translating between locations and positions. You can translate a location into a position on the map using the following API:

1
2
3
4
5
6
7
8
9
10
11

curl -X GET \
    https://api.{region}.te2.io/api/v1/public/venues/{venueId}/maps/{mapId}/@{latitude},{longitude} \
    -H 'Authorization: Bearer {token}'

{
  "position": {
    "x": 0.34605370227109233,
    "y": 0.2944832694802244
  },
  "inVenue": true
}

This API returns a JSON object containing the following fields:

Maps and points of interest

Points of interest (POI) are naturally related to the venue maps. You can retrieve information about POI using another API call:

1
2
3
4
5
6
7
8
9
10
11
12

curl -X GET \
    'https://api.{region}.te2.io/api/v2/pois?venueId={id}&mapId={mapId}' \
    -H 'Authorization: Bearer {token}'

    # This attribute is added to each POI object in the response
    "mapPosition": {
      "position": {
        "x": 0.5974999999998545,
        "y": 0.5111449676824122
      },
      "mapId": "2"
    }

In the above example, the map query string parameter is optional. If included, the API response will include the position of each POI on the map in the mapPosition attribute, with all transformations already applied.

For more information about POI and Venue APIs, refer to the Setup venues and POI guide.

Need help? Search our documentation or contact your assigned Client Engagement Manager.

Terms of use

© 2020 accesso Technology Group, plc.

All Rights Reserved.