Location tracking

Location tracking APIs let you retrieve current and last known user location. This data can be used to construct location history for a guest while they are inside the venue. This guide covers location tracking functionality from a mobile application perspective.

This guide assumes that a device has already been registered and that the user has been created. See the Register user devices guide for information on registering a device and obtaining an appUserId.

Reporting location data

The accesso Guest Experience platform uses a combination of GPS, Bluetooth, WiFi, and native mobile OS (Android or iOS) location services to pinpoint and track the location of a user device in relation to a venue.

Location information for a user device is reported through a POST to the /rest/user/device endpoint with location coordinates provided by the device’s GPS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -i -X POST \
  https://api.{region}.te2.io/rest/user/device \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "appUserId": "{appUserId}",
            "appId": "{appId}",
            "userId": "{userId}",
            "platform": "{platform}",
            "pushDeviceToken": "{pushDeviceToken}",
            "location": {
                "lat": 32.874624,
                "lon": -117.206651,
                "horizontalAccuracy": 65
            }
        }'

This will report user device {appUserId} at location (32.87462,-117.206651), with a horizontalAccuracy of 65 meters or better. The platform will then use the appId to determine if this location corresponds to any known venues for this application, and will trigger venue entry and exit events, depending on the current and last known location for this user device.

Determining venue entry and exit

The main mechanism for location tracking is the venue geofence, which is defined using a central latitude, longitude point and radius.

Latest venue data is retrieved by the mobile app using a GET to the /api/v1/public/venues/{venueId} endpoint.

A successful response includes the current venue location information, which is calculated from the geofence boundary.

The reponse also includes a JSON array of all geofences associated with the venue. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
  "geofences": [
    {
      "id": "{fenceId}",
      "venueId": "{venueId}",
      "name": "{name}",
      "label": "{label}",
      "radius": 375,
      "center": {
        "horizontalAccuracy": 5,
        "locationSource": "DEVICE",
        "lat": 32.874624,
        "lon": -117.206651,
      },
    }
  ]

(Full venue response can be found in the Venue API.)

The mobile app sets and tracks these geofences (using the center point with radius) and can determine whether the user device has crossed (breached) any of the tracked geofence boundaries.

Geofence breach events are reported by the user device to the platform using a POST to the /rest/user/device endpoint:

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
curl -i -X POST \
  'https://api.{region}.te2.io/rest/user/device?event=ENTER&fenceId=FENCE_123&locationSource=DEVICE' \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "appUserId": "{appUserId}",
            "appId": "{appId}",
            "userId": "{userId}",
            "platform": "{platform}",
            "pushDeviceToken": "{pushDeviceToken}",
            "location": {
                "lat": 32.874624,
                "lon": -117.206651,
                "horizontalAccuracy": 65,
                "locationSource": "DEVICE"
            },
            "appVersion": "1.23",
            "label": "Bob's phone",
            "tags": {
                "foo": "bar",
                "baz": "boo"
            },
            "ipAddress": "127.0.0.1",
            "ssid": "MyVenueWifiNetworkName",
            "bssid": "MyVenueWifiBSSID",
            "timestamp": 1561043804000
        }'

In the above request, we can see every field, query string parameter, and header that is considered by the device update endpoint.

The fields introduced here include:

• event: (query string) Indicates the direction of a geofence breach. If provided, expected values are ENTER, EXIT, or NONE.
• fenceId: (query string) The name of the geofence that was breached; usually the name of the venue.
• locationSource: (query string) Indicates how a geofence breach was inferred. If provided, the following are possible expected values:
  • BEACON - beacon detection
  • DEVICE - native iOS or Android services, such as GPS. This is the default value.
  • WIFI - external WiFi information
• appVersion: The version of the mobile app being used.
• label: The plaintext alias or nickname for the device.
• tags: Extension field for additional metadata about the device. Any keys and values in the provided object must be strings. This field is often an empty object or it is omitted entirely.
• ipAddress: When registering with a WiFi network, the IPv4 or IPv6 of the device.
• ssid: When registering with a WiFi network, the service set ID (SSID) of the network.
• bssid: When registering with a WiFi network, the basic service set identifier (BSSID) of the network.
• timestamp: The timestamp of the registration/update. Expected to be the number of milliseconds since the Unix epoch.

Tracking location within the venue

Once a user is reported to be inside the venue geofence, location updates can be retrieved and tracked using the device’s native location services.

If GPS is not enabled for the mobile device (and/or location permissions have not been granted to the app), user location can also be inferred through the following:

• If the mobile device is near a geofence already being tracked by the app, the app can detect location based on geofence proximity regardless of app permissions.
• If the venue is configured to use an external WiFi network, the device’s appUserId can be used to relay location information when detected by a wireless WiFi access point.

Additionally, if the mobile device has Bluetooth turned on, location can be inferred while in the venue through beacon pings. Beacons are Bluetooth, low-energy (BLE) devices placed by accesso throughout the venue. Each device has associated latitude, longitude coordinates, and these defined coordinates can provide general user location updates.

Mobile apps can discover beacon regions using a GET to the rest/venue/{venueId}/beacon/regions endpoint.

A successful 200 response returns an array of beacon regions within the stated venue that the app should monitor:

1
2
3
4
5
6
7
8
9
10
[
 {
  "proximityUUID": "{UUID}",
  "major": 123
 },
 {
  "proximityUUID": "{UUID}",
  "major": 234
 }
]

Where:

• proximityUUID: The unique identifier assigned to all client beacons. This can be shared across multiple venues.
• major: The major identifier for the beacon region in the stated venue. A venue can contain multiple beacon regions.

If the user device is in proximity to a beacon and the device has Bluetooth turned on, the beacon pings the app (ping rate and success is affected by the beacon’s broadcast range and power settings).

Mobile apps can report beacon sightings to the platform using a POST to the /rest/beacon/detect endpoint:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl -i -X POST \
 https://api.{region}.te2.io/rest/beacon/detect \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "appUserId": "{appUserId}",
            "appId": "{appId}",
            "timestamp": 1561043804000,
            "beacons": [
            {
                "proximityUUID": "{UUID}",
                "major": 123,
                "minor": 1
            } ]
        }'