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
{
"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
{
"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
{
"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
{
"bleType": "iBeacon",
"uuid": "451edb45-c1aa-4fa4-ad24-37b13bd81962",
"major": 5,
"minor": 3,
"txPower": -3
}
Eddystone-UID
{
"bleType": "Eddystone-UID",
"txPower": -3,
"namespace": "afc615557a94e6339cc5",
"instance": "3abe7844e03c"
}
Eddystone-URL
{
"bleType": "Eddystone-URL",
"txPower": -3,
"URL": "create.meraki.io"
}
Eddystone-TLM
{
"bleType": "Eddystone-TLM",
"version": 0,
"batteryVoltage": 1000,
"temperature": 0.0 ,
"advertisementCount": 12,
"secondsSincePowerUp": 7200.0
}
Eddystone-TLM encrypted
{
"bleType": "Eddystone-eTLM",
"version": 1,
"encryptedTLMData": "a840f320ab60a573ab60a573",
"salt": "bb33",
"interityCheck": "aa22"
}
Eddystone-EID encrypted
{
"bleType": "Eddystone-eEID",
"txPower": -3,
"eid": "a840f320ab60a573"
}
Unknown
{
"bleType": "unknown",
"rawdata": "a840f320ab60a573"
}