Location API version 3

API version 3 provides details of how the API works and how to get started building your own Location API receiver.

Overview

Using the physical placement of access points from Map & Floor Plans on the Dashboard, the Meraki cloud estimates the location of client devices observed. This data is then made available via the Scanning API. Since the floor plan on Dashboard are geo-aligned, this helps to accurate locate the client devices in the network. The following information will dive into the details of how the API works and how to get started building your own Scanning API receiver.

Requirements

  • A Meraki MR Wireless network
  • Firmware R26 for WiFi observations
  • Firmware R27.5 for BLE observations

What's New?

  • Scalability improvements for Scanning API v3, resulting in more accurate data in terms of reported clients and location updates.
  • Client userId information.
  • Consolidated observations to a single POST per network
  • Observation schema is now organized by clients instead of by access point
  • Improved location consistency (In v2 we saw variance from ~2m to 40m but with v3 we see location around ~2m to 2.5m consistently)
  • Floorplan information
  • Detailed RSSI readings

Changelog

New updates to v3

  • The userId property includes client userId (The userId can be an email, username or a phone number)

v2 to v3

  • The ipv4 property includes only the IP address, not client hostname
  • The type property now uses WiFi or BLE as potential values
  • The seenEpoch property has been removed
  • The apTags property is now labeled nearestApTags
  • A new data structure called rssiRecords has been added which includes the apMac and rssi properties
  • apFloors has been replaced with floorplan, which will provide better location to floorpan association
  • Clients using randomized MAC addresses will be parsed if they are associated to an SSID within the same Meraki network

Receiver Endpoints

The following endpoints will need to be provided from your custom Location API receiver. There are a number of examples provided in the Resources section of this page to help you get started.

Validator

Returns the validator string in the response body

[GET] https://youserver/

This endpoint is called by Meraki to validate the receiving server. It expects to receive a string that matches the validator defined in the Meraki Dashboard for the respective network.

Response Body

914732987423jhg2749273285k76fbokoy409845

Receiver

Accepts an observation payload from the Meraki cloud

[POST] https://yourserver

This endpoint is responsible for receiving the observation data provided by Meraki. The URL path should match that of the [GET] request, used for validation.

The response body will consist of an array of JSON objects containing the observations at an aggregate per network level. The JSON will be determined based on WiFi or BLE device observations as indicated in the type parameter.

Accuracy

Determining an accurate location for a WiFi or BLE client is a challenging task. Luckily, Meraki handles the hard part for you. Interference and obstacles can reduce the accuracy of a calculation. The variance parameter will determine the uncertainty in meters to help draw a circle around the possible location.

With the newer location algorithm we are triangulating the clients using a synchronization between all the APs in a Dashboard network. Since we are using the WiFi triangulation technique three or more APs are required to locate a client accurately. Incase the client device probes are not heard by three or more APs we will export the nearest AP and RSSI value as well to locate the client on the floor plan.

  • WiFi ~ 3.5 meters
  • BLE ~ 2.5 meters

Authentication & Security

The location data contains sensitive information about client and network details. The data stream is secured in a number of ways.

  • HTTPS Post URL with a valid TLS signed certificate to ensure encrypted transmission
  • Post URL validation to ensure receiving server identity
  • Shared secret to ensure sending server identity

Delivery Frequency

The Meraki access points will scan the wireless network and report their findings to the cloud. The cloud will then compute the location determined by the reported RSSI values. Finally, the observation payload is sent to the configured Location API receiver.

  • One JSON POST per network, per minute, per type (WiFi/BLE)
  • Expect up to an additional minute for the results to be gathered from the access points to be calculated in the cloud.

Observation Packet Size

A sample JSON payload containing 100 client observations will have a file size of approximately 100KB. The payload could vary in size depending on the client details and other network information.

  • 100 clients ~= 100KB per Location API POST