Observation Payloads

The JSON received from Meraki contains all of the calculated telemetry for proved Wi-Fi clients. Let's explore this data in more detail.

The schema below illustrates the general structure of an API message. The root of the body contains meta information that should be evaluated by your Location API receiver, followed by a data object containing the network and its client location observations. The locations array will contain a recent history of the clients movement between each API post. If a client is no longer discoverable, a latestRecord object will contain the last access point to hear the client and the time of the event.

WiFi Properies

json

Copy{
    "version": number,
    "secret": string,
    "type": string,
    "data": {
      "networkId": string,
      "observations": [
          {
              "locations": [
                  {
                      "x": number,
                      "lng": number,
                      "rssiRecords": [
                          {
                              "apMac": string,
                              "rssi": number
                          },
                          {
                              "apMac": string,
                              "rssi": number
                          },
                          {
                              "apMac": string,
                              "rssi": number
                          }
                      ],
                      "variance": number,
                      "y": string,
                      "nearestApTags": [string],
                      "floorPlanId": string,
                      "time": ISO time,
                      "lat": string
                  }
              ],
              "ipv4": string,
              "ssid": string,
              "os": string,
              "clientMac": string,
              "ipv6": string,
              "userId": string,
              "manufacturer": string,

              // IF no recent locations
              "latestRecord": {
                  "time": string,
                  "nearestApMac": string,
                  "nearestApRssi": string
              }
          }
      ]
    }
}

WiFi Properties

`root {}`

Name	Format	Description
data	object	The client observation data from a network.
secret	string	The shared secret between Meraki and the receiver. Check the value against your receivers configured secret to ensure that your Meraki network is the one actually sending the data.
type	string	The type will be of either WiFi or BLE, which will determine the data observation's schema and allow you to route the data appropriately.
version	string	The semantic version of the Scanning API post payload. A receiver should route messages on the major version number. Minor updates will periodically occur and configured receivers will automatically recieve this payload version going forward. For instance, a receiver may receive posts with a version of 3.0 but as Meraki adds non-breaking enhancements to the payload, the minor version will increment to 3.1, 3.2, 3.3, etc..

`data {}`

Name	Format	Description
networkId	string	The Meraki network ID
observations	array of objects	An array of client observations containg location telemetry

`observations []`

Name	Format	Description
clientMac	string	Client MAC address
floorPlanId	string	Floor plan Id to identify them uniquely, example: “g_1234567”
floorPlanName	string	Floor plan name uploaded on Dashboard
ipv4	string	Client IPv4 address
ipv6	string	Client IPv6 address
userId	string	Client user ID (e.g. email, username, phone number)
lat	decimal	Device latitude in degrees N of the equator
latestRecord	array of objects	This will have the information of the AP MAC address and the RSSI value when the client is seen by 3 or less APs
lng	decimal	Device longitude in degrees E of the prime meridian
locations	array of objects	Device geolocation; null if location could not be determined

`latestRecord {}`

Name	Format	Description
nearestApMac	string	MAC address of nearest access point
nearestApRssi	string	RSSI value of nearest API; -96 if client packet not detected
time	ISO 8601 date string	Observation time in UTC; example: “1970-01-01T00:00:00Z”

`locations []`

Name	Format	Description
manufacturer	string	Device manufacturer; null if manufacturer could not be determined
nearestApTags	array of strings	Will provide a list of assigned tags to the AP
os	string	Device operating system; null if the OS could not be determined
rssiRecords	array of objects	Client device RSSI as seen by individual APs
ssid	string	Client SSID name; null if the device is not connected
time	ISO 8601 date string	Observation time in UTC; example: “1970-01-01T00:00:00Z”
variance	decimal	Difference between the actual location and the mathematical model used.
x	decimal	JSON array of x offsets (in meters) from lower-left corner of each floorplan
y	decimal	JSON array of y offsets (in meteres) from lower-left corner of each floorplan

WiFi Payload Example

type: WiFi

json

Copy{
  "version": "3.0",
  "secret": "supersecret",
  "type": "WiFi",
  "data": {
    "networkId": "L_000000000000000001",
    "observations": [
      {
        "locations": [
          {
            "x": "7.976651798199431",
            "lng": 6.0957744807924485,
            "floorPlanName": "3rd Floor",
            "rssiRecords": [
              {
                "apMac": "aa:aa:aa:11:11:11",
                "rssi": -32
              },
              {
                "apMac": "aa:aa:aa:22:22:22",
                "rssi": -54
              },
              {
                "apMac": "aa:aa:aa:33:33:33",
                "rssi": -51
              }
            ],
            "variance": 1.6885258062410806,
            "y": "10.576847081490314",
            "nearestApTags": ["", "API-TEST", "Office", ""],
            "floorPlanId": "g_643451796760560979",
            "time": "2019-11-28T14:27:21Z",
            "lat": 60.05342983801672
          },
          {
            "x": "8.013339145491448",
            "lng": 6.095772908171716,
            "floorPlanName": "3rd Floor",
            "rssiRecords": [
              {
                "apMac": "aa:aa:aa:33:33:33",
                "rssi": -52
              },
              {
                "apMac": "aa:aa:aa:11:11:11",
                "rssi": -32
              },
              {
                "apMac": "aa:aa:aa:22:22:22",
                "rssi": -51
              }
            ],
            "variance": 1.6201842796909718,
            "y": "10.697906571736747",
            "nearestApTags": ["", "API-TEST", "Office", ""],
            "floorPlanId": "g_643451796760560979",
            "time": "2019-11-28T14:27:35Z",
            "lat": 60.05342922730819
          },
          {
            "x": "8.591860719528196",
            "lng": 6.095759658672512,
            "floorPlanName": "3rd Floor",
            "rssiRecords": [
              {
                "apMac": "aa:aa:aa:11:11:11",
                "rssi": -34
              },
              {
                "apMac": "aa:aa:aa:22:22:22",
                "rssi": -51
              },
              {
                "apMac": "aa:aa:aa:44:44:44",
                "rssi": -45
              },
              {
                "apMac": "aa:aa:aa:33:33:33",
                "rssi": -51
              }
            ],
            "variance": 1.5097088029182084,
            "y": "11.404523745521399",
            "nearestApTags": ["", "API-TEST", "Office", ""],
            "floorPlanId": "g_643451796760560979",
            "time": "2019-11-28T14:27:46Z",
            "lat": 60.053427800388225
          }
        ],
        "ipv4": "192.168.0.251",
        "ssid": ".interwebs",
        "os": "Eye-Fi Wireless Memory Card",
        "clientMac": "cc:cc:cc:11:11:11",
        "latestRecord": {
          "time": "2019-11-28T14:27:57Z",
          "nearestApMac": "aa:aa:aa:44:44:44",
          "nearestApRssi": "-47"
        },
        "ipv6": null,
        "userId": "123abc@cisco.com",
        "manufacturer": "Espressif"
      },
      {
        "locations": [],
        "ipv4": "192.168.0.214",
        "ssid": ".interwebs",
        "os": "Meraki Network OS",
        "clientMac": "cc:cc:cc:22:22:22",
        "latestRecord": {
          "time": "2019-11-28T14:27:40Z",
          "nearestApMac": "aa:aa:aa:55:55:55",
          "nearestApRssi": "-62"
        },
        "ipv6": null,
        "userId": "device-Aisg2OEYYq8732tfEz6bb",
        "manufacturer": "Meraki"
      }
    ]
  }
}

BLE Properties

`data {}`

Name	Format	Description
networkId	String	Consists of the network ID for the given network
startTime	ISO 8601 date string	Observation time in UTC
endTime	ISO 8601 date string	Observation time in UTC
reportingAps	Array	Indicating all the APs seen by the client between the start and end time
mac	String	MAC address of the APs
serial	String	S/N of the APs
name	String	Name of the AP in Dashboard
tags	String	Tags assigned to the AP in Dashboard
lat	Decimal	Device latitude in degrees N of the equator
lng	Decimal	Device longitude in degrees N of the equator
floorplanid	Decimal	Floor plan ID to identify uniquely
name	String	Name of the floor plan
x	Decimal	JSON array of x offsets(in meters) from lower left corner of the floor plan
y	Decimal	JSON array of y offsets(in meters) from lower left corner of the floor plan

`reportingAps []`

Name	Format	Description
mac	String	MAC address of the APs
serial	String	S/N of the APs
name	String	Name of the AP in Dashboard
tags	String	Tags assigned to the AP in Dashboard
lat	Decimal	Device latitude in degrees N of the equator
lng	Decimal	Device longitude in degrees N of the equator
floorplanid	Decimal	Floor plan ID to identify uniquely
name	String	Name of the floor plan
x	Decimal	JSON array of x offsets(in meters) from lower left corner of the floor plan
y	Decimal	JSON array of y offsets(in meters) from lower left corner of the floor plan

`observations []`

Name	Format	Description
clientMac	String	Client MAC address
name	String	Name of the client
latestRecord	Array	Array of all the records seen by the APs
nearestApMac	String	MAC address of the nearest AP
nearestApRssi	String	Client device RSSI seen by the nearestApMac
time	ISO 8601 date string	Time stamp when the client was seen

`locations []`

Name	Format	Description
lat	Decimal	Client device latitude in degrees N of the equator
lng	Decimal	Client device longitude in degrees N of the equator
variance	Decimal	Difference between mathematical model and actual location (unit is meters)
floorplan	String	Floor plan name in Dashboard
id	Decimal	Floor plan ID where the client has been located
x	Decimal	JSON array of x offsets(in meters) from lower left corner of the floor plan
y	Decimal	JSON array of y offsets(in meters) from lower left corner of the floor plan

`bleBeacons []`

Name	Format	Description
bleType	String	BLE type to indicate the BLE client
major	String	Major value configured in the BLE beacons from client
minor	String	Minor value configured in the BLE beacons from client
txPower	String	Transmit power the beacons
uuid	String	Uniques UUID configured on per client basis to identify each client individually

BLE Payload Example

json

Copy{
    "version": "3.0",
    "secret": "supersecret",
    "type": "Bluetooth",
    "data": {
        "networkId": "L_123456789012345678",
        "startTime": "2020-08-20T14:32:40Z",
        "reportingAps": [
            {
                "serial": "Q2RD-4E2X-XXXX",
                "mac": "e0:cb:bc:45:a4:74",
                "name": "Office - North",
                "lng": 5.5957659188658,
                "tags": [
                    "",
                    "API-TEST",
                    "Office",
                    ""
                ],
                "floorPlan": {
                    "id": "g_643451796760560979",
                    "name": "3rd Floor",
                    "x": 8.571617078867233,
                    "y": 10.776322973491894
                },
                "lat": 55.55343196761682
            }
        ],
        "endTime": "2020-08-20T14:33:40Z",
        "observations": [

            {
                "locations": [
                    {
                        "lng": 5.595782199038956,
                        "rssiRecords": [
                            {
                                "apMac": "88:15:44:aa:a9:ff",
                                "rssi": -57
                            },
                            {
                                "apMac": "0c:8d:db:7b:2b:ff",
                                "rssi": -76
                            },
                            {
                                "apMac": "e0:cb:bc:45:fe:ff",
                                "rssi": -68
                            },
                            {
                                "apMac": "e0:cb:bc:45:a4:ff",
                                "rssi": -86
                            }
                        ],
                        "variance": 6.942336838846548,
                        "floorPlan": {
                            "id": "g_6434517967605609ff",
                            "name": "3rd Floor",
                            "x": 5.724940366867569,
                            "y": 12.391871362171393
                        },
                        "nearestApMac": "88:15:44:aa:a9:ff",
                        "time": "2020-08-20T14:32:41Z",
                        "lat": 55.55340424435369
                    }
                    
                ],
                "name": "",
                "bleBeacons": [
                    {
                        "uuid": "b9407f30-f5f8-466e-aff9-25556b57feff",
                        "txPower": -63,
                        "major": 3431,
                        "bleType": "iBeacon",
                        "minor": 42342
                    }
                ],
                "clientMac": "e6:ae:f1:79:8f:ff",
                "latestRecord": {
                    "time": "2020-08-20T14:33:33Z",
                    "nearestApMac": "88:15:44:aa:a9:ff",
                    "nearestApRssi": -57
                }
            }           
        ]
    }
}

`bleBeacons [] {}`

example beacon payloads

iBeacon

json

Copy
 {
    "bleType": "iBeacon",
    "uuid": "451edb45-c1aa-4fa4-ad24-37b13bd81962",  
    "major": 5,
    "minor": 3,
    "txPower": -3
 }

Eddystone-UID

json

Copy
{
    "bleType": "Eddystone-UID",
    "txPower": -3,
    "namespace": "afc615557a94e6339cc5",
    "instance": "3abe7844e03c"
}

Eddystone-URL

json

Copy
{
    "bleType": "Eddystone-URL",
    "txPower": -3,
    "URL": "create.meraki.io"
}

Eddystone-TLM

json

Copy
{
    "bleType": "Eddystone-TLM",
    "version": 0,
    "batteryVoltage": 1000,
    "temperature": 0.0 ,
    "advertisementCount": 12,
    "secondsSincePowerUp": 7200.0
}

Eddystone-TLM encrypted

json

Copy{
    "bleType": "Eddystone-eTLM",
    "version": 1,
    "encryptedTLMData": "a840f320ab60a573ab60a573", 
    "salt": "bb33",
    "interityCheck": "aa22"
}

Eddystone-EID encrypted

json

Copy
{
    "bleType": "Eddystone-eEID",
    "txPower": -3,
    "eid": "a840f320ab60a573" 
}

Unknown

json

Copy{
  "bleType": "unknown",
  "rawdata": "a840f320ab60a573" 
}