Location

GET: Active RFID Tags Count

Description

This API returns active RFID tags count.

HTTP Method

GET

Resource URI

/api/location/v1/tags/count

Requires OAuth

N

Parameters

None.

Content Type

application/json

Sample Output

{
"deviceType":"Tag",
"deviceQueryString":null,
"count":8
}

GET: All Tags

Description

This API returns all tags.

HTTP Method

GET

Resource URI

/api/location/v1/tags

Requires OAuth

N

Parameters

None.

Content Type

application/json

Sample Output (JSON)

[
    {
        "macAddress": "98:07:2d:2a:13:f0",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor>Tm",
            "floorRefId": "727035700041482264",
            "floorDimension": {
                "length": 49.9,
                "width": 81,
                "height": 10,
                "offsetX": 0,
                "offsetY": 0,
                "unit": "FEET"
            },
            "image": {
                "imageName": "domain_0_1461628766707.png",
                "zoomLevel": 4,
                "width": 2008,
                "height": 1097,
                "size": 2008,
                "maxResolution": 8,
                "colorDepth": 8
            }
        },
        "mapCoordinate": {
            "x": 46.621124,
            "y": 43.95517,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 88,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-04T00:05:41.824-0800",
            "firstLocatedTime": "2017-12-04T00:05:30.305-0800",
            "lastLocatedTime": "2017-12-04T00:05:36.315-0800",
            "maxDetectedRssi": {
                "apMacAddress": "cc:16:7e:32:63:60",
                "band": "IEEE_802_11_B",
                "slot": 0,
                "rssi": -59,
                "antennaIndex": 0,
                "lastHeardInSeconds": 6
            }
        },
        "historyLogReason": null,
        "geoCoordinate": {
            "latitude": 37.42250281440575,
            "longitude": -121.95978545449093,
            "unit": "DEGREES"
        },
        "rawLocation": {
            "rawX": -999,
            "rawY": -999,
            "unit": "FEET"
        },
        "networkStatus": "ACTIVE",
        "changedOn": 1512374736315,
        "telemetryList": null,
        "batteryInfo": null,
        "vendorData": null,
        "sortedEmergencyList": null,
        "sortedChokepointList": null,
        "lastBeaconTime": null,
        "lastBeaconSequenceNumber": 0,
        "deviceSubtype": "BLE",
        "bleAttributesList": [
            {
                "profileType": "IBEACON",
                "deviceName": "",
                "uuid": "20CAE8A0A9CF11E3A5E20800200C9A66",
                "major": 42,
                "minor": 5104,
                "power": -70,
                "frequency": 0,
                "revision": 0,
                "battery": 0,
                "firmware": null,
                "hardware": null,
                "eddystoneURL": "",
                "eddystoneNamespace": "",
                "eddystoneInstanceid": "",
                "batteryObject": [
                    {
                        "sourceIndex": 1,
                        "percentage": 0,
                        "milliVolts": 0
                    },
                    {
                        "sourceIndex": 2,
                        "percentage": 0,
                        "milliVolts": 0
                    },
                    {
                        "sourceIndex": 3,
                        "percentage": 0,
                        "milliVolts": 0
                    }
                ]
            }
        ],
        "manufacturer": "Texas Instruments"
    },
    {
        "macAddress": "98:07:2d:2a:11:c0",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor>CMX Bar",
            "floorRefId": "727035700041482264",
            "floorDimension": {
                "length": 49.9,
                "width": 81,
                "height": 10,
                "offsetX": 0,
                "offsetY": 0,
                "unit": "FEET"
            },
            "image": {
                "imageName": "domain_0_1461628766707.png",
                "zoomLevel": 4,
                "width": 2008,
                "height": 1097,
                "size": 2008,
                "maxResolution": 8,
                "colorDepth": 8
            },
            "tagList": [
                "Lobby"
            ]
        },
        "mapCoordinate": {
            "x": 52.03835,
            "y": 23.021484,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 120,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-04T00:05:41.825-0800",
            "firstLocatedTime": "2017-12-04T00:05:36.306-0800",
            "lastLocatedTime": "2017-12-04T00:05:36.306-0800",
            "maxDetectedRssi": {
                "apMacAddress": "f8:0b:cb:3c:01:80",
                "band": "IEEE_802_11_B",
                "slot": 0,
                "rssi": -68,
                "antennaIndex": 0,
                "lastHeardInSeconds": 1
            }
        },
        "historyLogReason": null,
        "geoCoordinate": {
            "latitude": 37.4224445499256,
            "longitude": -121.9598048699379,
            "unit": "DEGREES"
        },
        "rawLocation": {
            "rawX": -999,
            "rawY": -999,
            "unit": "FEET"
        },
        "networkStatus": "ACTIVE",
        "changedOn": 1512374736306,
        "telemetryList": null,
        "batteryInfo": null,
        "vendorData": null,
        "sortedEmergencyList": null,
        "sortedChokepointList": null,
        "lastBeaconTime": null,
        "lastBeaconSequenceNumber": 0,
        "deviceSubtype": "BLE",
        "bleAttributesList": [
            {
                "profileType": "IBEACON",
                "deviceName": "",
                "uuid": "20CAE8A0A9CF11E3A5E20800200C9A66",
                "major": 42,
                "minor": 4544,
                "power": -70,
                "frequency": 0,
                "revision": 0,
                "battery": 0,
                "firmware": null,
                "hardware": null,
                "eddystoneURL": "",
                "eddystoneNamespace": "",
                "eddystoneInstanceid": "",
                "batteryObject": [
                    {
                        "sourceIndex": 1,
                        "percentage": 0,
                        "milliVolts": 0
                    },
                    {
                        "sourceIndex": 2,
                        "percentage": 0,
                        "milliVolts": 0
                    },
                    {
                        "sourceIndex": 3,
                        "percentage": 0,
                        "milliVolts": 0
                    }
                ]
            }
        ],
        "manufacturer": "Texas Instruments"
    }
]

GET: RFID Tag by MAC Address

Description

This API returns an RFID tag by its MAC address.

HTTP Method

GET

Resource URI

/api/location/v1/tags/:macaddress

Requires OAuth

N

Parameters

Table 1. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

—

String

pathReplace

RFID Tag MAC address.

Content Type

application/json

Sample Output

http://10.68.40.131/api/location/v1/tags/00:18:8e:28:24:26

{
          "macAddress": "00:18:8e:28:24:26",
          "mapInfo": {
                    "mapHierarchyString": "Singapore>SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>SingZone",
                    "floorRefId": "739764660256899136",
                    "floorDimension": {
                              "length": 118.11024,
                              "width": 184.05511,
                              "height": 9.84252,
                              "offsetX": 0,
                              "offsetY": 0,
                              "unit": "FEET"
                    },
                    "image": {
                              "imageName": "domain_0_1380690706964.png",
                              "zoomLevel": 4,
                              "width": 1440,
                              "height": 900,
                              "size": 1440,
                              "maxResolution": 8,
                              "colorDepth": 8
                    }
          },
          "mapCoordinate": {
                    "x": 108.84515,
                    "y": 68.62626,
                    "z": 0,
                    "unit": "FEET"
          },
          "currentlyTracked": true,
          "confidenceFactor": 72,
          "statistics": {
                    "currentServerTime": "2016-06-16T02:20:42.974+0800",
                    "firstLocatedTime": "1970-01-01T07:30:00.000+0730",
                    "lastLocatedTime": "2016-06-16T02:20:39.336+0800",
                    "maxDetectedRssi": {
                              "apMacAddress": "64:f6:9d:2a:05:00",
                              "band": "IEEE_802_11_B",
                              "slot": 0,
                              "rssi": -58,
                              "antennaIndex": 0,
                              "lastHeardInSeconds": 1
                    }
          },
          "historyLogReason": null,
          "geoCoordinate": {
                    "latitude": 1.3347778969996247,
                    "longitude": 103.96366325767761,
                    "unit": "DEGREES"
          },
          "networkStatus": "ACTIVE",
          "changedOn": 1466014839336,
          "telemetryList": null,
          "batteryInfo": {
                    "tolerance": 70,
                    "percentRemaining": 100,
                    "daysRemaining": 0,
                    "batteryAge": 0,
                    "lastReceivedTime": "2016-06-09T06:38:29.748+0800",
                    "lastReceivedSeqNum": 2221
          },
          "vendorData": {
                    "vendorId": 6286,
                    "elementId": 0,
                    "data": "AAMAAQEABAABAQ==",
                    "lastReceivedTime": "2016-06-09T06:38:29.748+0800",
                    "lastReceivedSeqNum": 2221
          },
          "sortedEmergencyList": null,
          "sortedChokepointList": null,
          "lastBeaconTime": null,
          "lastBeaconSequenceNumber": 2221,
          "manufacturer": "Ekahau"
}

GET: Supported Northbound Notifications

Description

This API returns all supported notification types and applicable attributes for the notification rules.

HTTP Method

GET

Resource URI

/api/location/v1/attributes

Requires Basic Auth

N

Content Type

application/json

Sample Output

{
   "notifications":[
      {
         "notificationType":"locationupdate",
         "subscriptionName":"asdasdasd",
         "eventId":1259951,
         "locationMapHierarchy":"Simulator-1212-Campus0>Building1>Floor8>Zone4",
         "locationCoordinate":{
            "x":65.32642,
            "y":302.04172,
            "z":0.0,
            "unit":"FEET"
         },
         "geoCoordinate":{
            "latitude":-999.0,
            "longitude":-999.0,
            "unit":"DEGREES"
         },
         "confidenceFactor":64.0,
         "apMacAddress":"NOT APPLICABLE",
         "associated":false,
         "username":"NOT APPLICABLE",
         "ipAddress":[
            "NOT APPLICABLE"
         ],
         "ssid":"NOT APPLICABLE",
         "band":"NOT APPLICABLE",
         "floorId":1721918422,
         "entity":"WIRELESS_CLIENTS",
         "deviceId":"10:00:00:00:0f:5e",
         "lastSeen":"2017-06-06T13:42:51.798-0700",
         "rawLocation":{
            "rawX":-999.0,
            "rawY":-999.0,
            "unit":"FEET"
         },
         "areaGlobalidList":[
            6343,
            2759,
            2758,
            2757,
            6399,
            6400,
            6289,
            6342
         ],
         "tagVendorData":null,
         "manufacturer":"Private",
         "timestamp":1496781771798
      }
   ]
}
 

Output Field Descriptions

Table 2. Output Field Descriptions

Field

Description

Notification Type

What type of notification this output describes (For example, locationupdate)

Subscription Name

The name of the notification created in CMX (user provided)

Event ID

Unique for notification identification per event

Location Map Hierarchy

The Hierarchy string that shows campus, building, floor, and zone (if applicable)

Location Coordinate

XY location for the device

Geo Coordinate

GPS location for device, if GPS markers are set

Confidence Factor

Represents a square box of where the client should be, lower means better location accuracy

AP Mac Address

The AP that the client is connected to

Associated

is this device Associated or not

Username

The username of this Associated client if using 802.11x

IP address

If this client is associated, what IP address(es) are assigned to it, can include IPv4 and IPv6 addresses

SSID

The SSID of the client is Associated

Band

802.11 band the device is it connected to

Floor Id

Long value representing hieracrchy, would not use

Floor Ref Id

Represents a long for what hierarchy it is on (Floor Id might be rounded if the number is large enough due to a conversion from long to double), only is filled in for location update, recommended for use

Entity

What type of device is it, Client (normal devices), RFID Tag (these are devices that send a chirp on an interval), Interferers (Devices that are connected to APs or are APs that aren’t on the network controlled by a controller on this CMX)

Device Id

MAC address of device

Last Seen

Timestamp of packet last received from controller for this device

Raw Location

-

Area Global Id List

-

Tag Vendor Data

For RFID tags, information that was encoded in packets we received like battery life or something like that.

Manufacturer

Based on the first half of the MAC address of this device

Timestamp

When the notification generated

status

Refers to what the status of the device is - IDLE(0), AAA_PENDING(1), AUTHENTICATED(2),

ASSOCIATED(3), POWERSAVE(4), DISASSOCIATED(5), TO_BE_DELETED(6), PROBING(7),

BLACK_LISTED(8), WAIT_AUTHENTICATED(256), WAIT_ASSOCIATED(257);

Table 3. API History

Release

Modification

Cisco CMX Release 10.3

Output field descriptor Floor Ref Id was introduced.

GET: Count of all the Beacons

Description

This API returns count of all beacons.

HTTP Method

GET

Resource URI

/api/location/v1/beacon/count

Requires OAuth

N

Parameters

None.

Content Type

application/json

Sample Output

http://10.68.40.131/api/location/v1/beacon/count

28

PUT: Place a Beacon at Detected Location on Map

Description

This API places a beacon at detected location on the map.

HTTP Method

PUT

Resource URI

/api/location/v1/beacon/replace/:macaddress

Requires OAuth

N

Parameters

Table 4. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

—

String

pathReplace

Mac address of beacon.

Content Type

application/json

PUT: Updates Name of a Given Beacon

Description

This API updates the name of a given Beacon.

HTTP Method

PUT

Resource URI

/api/location/v1/beacon/name/:macaddress/:name

Requires OAuth

N

Parameters

Table 5. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

—

String

pathReplace

Mac address of beacon.

name

Y

—

String

pathReplace

New values to be used as name.

Content Type

application/json

GET: List of Beacons Matching Filter Criteria

Description

This API returns list of Beacons matching to filter criteria present on the given floor. filterString format :mac={mac} name={name} uuid={uuid} major={major} minor={minor} example : api/location/v1/veacon/search/{floorrefid}/mac=11:22:33:44:55:66 name=abc

HTTP Method

GET

Resource URI

/api/location/v1/beacon/search/:floorrefid/:filterString

Requires OAuth

N

Parameters

Table 6. Parameter Details

Name

Required

Default

Type

Location

Description

floorrefid

Y

—

Number

pathReplace

Reference id of the floor.

filterString

Y

—

String

pathReplace

Value of the filterString.

Content Type

application/json

POST: Add Beacon with Minimum Fields

Description

This API adds a beacon with minimum fields to the store. Example query string /info/mac={mac} and name={name} and uuid={uuid} and major={major} and minor={minor}.

HTTP Method

POST

Resource URI

/api/location/v1/beacon/info/:queryString

Requires OAuth

N

Parameters

Table 7. Parameter Details

Name

Required

Default

Type

Location

Description

queryString

Y

—

String

pathReplace

Value of the queryString.

Content Type

application/json

GET: Beacons with Minimum Information for a Floor ID

Description

This API returns beacons with minimum information for a floor ID.

HTTP Method

GET

Resource URI

/api/location/v1/beacon/info/:floorrefid

Requires OAuth

N

Parameters

Table 8. Parameter Details

Name

Required

Default

Type

Location

Description

floorrefid

Y

—

Number

pathReplace

Reference ID of the floor.

Content Type

application/json

Sample Output

http://10.68.40.131/api/location/v1/beacon/info/739764660256899136

["MAC- c8:69:cd:54:2c:3a UUID-null MAJOR-null MINOR-null TYPE-Rogue STATUS-Active RSSI-null","MAC- e7:8e:65:42:7b:5e UUID-b9:40:7f:30:f5:f8:46:6e:af:f9:25:55:6b:57:fe:6d MAJOR-31582 MINOR-25922 TYPE-Rogue STATUS-Active RSSI--74","MAC- f8:25:1d:38:5f:df UUID-b9:40:7f:30:f5:f8:46:6e:af:f9:25:55:6b:57:fe:6d MAJOR-24543 MINOR-7480 TYPE-Rogue STATUS-Active RSSI--74","MAC- c8:69:cd:50:29:de UUID-null MAJOR-null MINOR-null TYPE-Rogue STATUS-Active RSSI-null"]

GET: List of Beacons

Description

This API returns list of Beacons.

HTTP Method

GET

Resource URI

/api/location/v1/beacon

Requires OAuth

N

Parameters

None.

Content Type

application/json

Sample Output

http://10.68.40.131/api/location/v1/beacon

[{"macAddress":"c8:69:cd:54:2c:3a","name":null,"type":"Rogue",
"detectedOn":1465384031100,"status":"Active","lastUpdatedOn":1466015949748,
"currentServerTime":1466016244167,"expectedHierarchyString":null,"actualHierarchyString":
null,"uuid":null,"major":null,"minor":null,"manufacturerId":null,"rssi":null,"mapInfo":
{"mapHierarchyString":"Singapore>SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>IOT Demo,
SingZone","floorRefId":"739764660256899136"},"mapCoordinate":{"x":79.47438,"y":60.84791,
"z":0.0,"unit":"FEET"},"detectedLocation":null,"configuredLocation":null,"lastUpdatedTime":
1466015949748},{"macAddress":"e7:8e:65:42:7b:5e","name":null,"type":"Rogue","detectedOn":
1466007673699,"status":"Active","lastUpdatedOn":0,"currentServerTime":1466016244167,
"expectedHierarchyString":null,"actualHierarchyString":null,"uuid":
"b9:40:7f:30:f5:f8:46:6e:af:f9:25:55:6b:57:fe:6d","major":"31582","minor":"25922",
"manufacturerId":"4c00","rssi":"-74","mapInfo":{"mapHierarchyString":"Singapore>
SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>SingZone","floorRefId":"739764660256899136"},
"mapCoordinate":{"x":110.90741,"y":62.45491,"z":0.0,"unit":"FEET"},"detectedLocation":
null,"configuredLocation":null,"lastUpdatedTime":0},

………

{"mapHierarchyString":"Bangalore_Cessna>Building 11>Customer Experience Center",
"floorRefId":"739764720386534870"},"mapCoordinate":{"x":91.889755,"y":161.0643,"z":0.0,
"unit":"FEET"},"detectedLocation":null,"configuredLocation":null,"lastUpdatedTime":0},
{"macAddress":"34:c0:59:36:71:1d","name":null,"type":"Rogue","detectedOn":1466015514702,
"status":"Active","lastUpdatedOn":0,"currentServerTime":1466016244167,
"expectedHierarchyString":null,"actualHierarchyString":null,"uuid":null,"major":null,
"minor":null,"manufacturerId":null,"rssi":null,"mapInfo":{"mapHierarchyString":
"Bangalore_Cessna>Building 11>Customer Experience Center","floorRefId":
"739764720386534870"},"mapCoordinate":{"x":91.889755,"y":161.0643,"z":0.0,"unit":"FEET"},
"detectedLocation":null,"configuredLocation":null,"lastUpdatedTime":0}]

GET: Beacon by MAC Address

Description

This API returns Beacon by macaddress.

HTTP Method

GET

Resource URI

/api/location/v1/beacon/:macaddress

Requires OAuth

N

Parameters

Table 9. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

—

String

pathReplace

Mac address of beacon.

Content Type

application/json

Sample Output

http://10.68.40.131/api/location/v1/beacon/c8:69:cd:54:2c:3a

{"macAddress":"c8:69:cd:54:2c:3a","name":null,"type":"Rogue",
"detectedOn":1465384031100,"status":"Active","lastUpdatedOn":1466015949748,
"currentServerTime":1466016328698,"expectedHierarchyString":null,"actualHierarchyString":
null,"uuid":null,"major":null,"minor":null,"manufacturerId":null,"rssi":null,"mapInfo":
{"mapHierarchyString":"Singapore>SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>SingZone",
"floorRefId":"739764660256899136"},"mapCoordinate":{"x":76.43114,"y":58.149662,"z":0.0,
"unit":"FEET"},"detectedLocation":null,"configuredLocation":null,"lastUpdatedTime":
1466015949748}

DELETE: Delete Beacon by MAC Address

Description

This API deletes a Beacon by macaddress.

HTTP Method

DELETE

Resource URI

/api/location/v1/beacon/:macaddress

Requires OAuth

N

Parameters

Table 10. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

—

String

pathReplace

Mac address of beacon to be deleted.

Content Type

application/json

PUT: Update Beacon

Description

This API updates a given Beacon.

HTTP Method

PUT

Resource URI

/api/location/v1/beacon

Requires OAuth

N

Parameters

Table 11. Parameter Details

Name

Required

Default

Type

Location

Description

macAddress

Y

—

string

body

MAC Address.

name

Y

—

string

body

Name

type

N

—

enumerated

body

  • Known

  • Rogue

  • Unplaced

detectedOn

N

—

number

body

detectedOn

status

N

—

enumerated

body

  • Active

  • Missing

  • Misplaced

  • Inactive

  • NeverDetected

lastUpdatedOn

N

—

number

body

Last updated on.

expectedHierarchyString

N

—

string

body

Expected Hierarchy String.

actualHierarchyString

N

—

string

body

Actual Hierarchy String.

uuid

Y

—

string

body

UUID

major

Y

—

string

body

Major.

minor

Y

—

string

body

Minor

manufacturerId

N

—

string

body

Manufacturer ID

rssi

N

—

string

body

RSSI value.

mapInfo

N

—

text

body

Map Information.

mapCoordinate

N

—

text

body

Map coordinate.

detectedLocation

N

—

text

body

Detected Location.

configuredLocation

N

—

text

body

Configured Location.

Content Type

application/json

GET: List of Beacons Present on a Floor

Description

This API returns list of Beacons present on the given floor.

HTTP Method

GET

Resource URI

/api/location/v1/beacon/floor/:floorrefid

Requires OAuth

N

Parameters

Table 12. Parameter Details

Name

Required

Default

Type

Location

Description

floorrefid

Y

—

Number

pathReplace

Reference ID of the floor.

Content Type

application/json

Sample Output

[{"macAddress":"c8:69:cd:54:2c:3a","name":null,"type":"Rogue","detectedOn":
1465384031100,"status":"Active","lastUpdatedOn":1466015949748,"currentServerTime":
1466016486617,"expectedHierarchyString":null,"actualHierarchyString":null,"uuid":null,
"major":null,"minor":null,"manufacturerId":null,"rssi":null,"mapInfo":
{"mapHierarchyString":"Singapore>SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>SingZone",
"floorRefId":"739764660256899136"},"mapCoordinate":{"x":76.43114,"y":58.149662,"z":0.0,
"unit":"FEET"},"detectedLocation":null,"configuredLocation":null,"lastUpdatedTime":
1466015949748},{"macAddress":"e7:8e:65:42:7b:5e","name":null,"type":"Rogue","detectedOn":
1466007673699,"status":"Active","lastUpdatedOn":0,"currentServerTime":1466016486617,
"expectedHierarchyString":null,"actualHierarchyString":null,"uuid":
"b9:40:7f:30:f5:f8:46:6e:af:f9:25:55:6b:57:fe:6d","major":"31582","minor":"25922",
"manufacturerId":"4c00","rssi":"-74","mapInfo":{"mapHierarchyString":
"Singapore>SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>SingZone","floorRefId":
"739764660256899136"},"mapCoordinate":{"x":110.90741,"y":62.45491,"z":0.0,"unit":"FEET"},
"detectedLocation":null,"configuredLocation":null,"lastUpdatedTime":0},
{"macAddress":"f8:25:1d:38:5f:df","name":null,"type":"Rogue","detectedOn":1465803834008,
"status":"Active","lastUpdatedOn":1466012481898,"currentServerTime":1466016486617,
"expectedHierarchyString":null,"actualHierarchyString":null,"uuid":
"b9:40:7f:30:f5:f8:46:6e:af:f9:25:55:6b:57:fe:6d","major":"24543","minor":"7480",
"manufacturerId":"4c00","rssi":"-74","mapInfo":{"mapHierarchyString":
"Singapore>SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>SingZone","floorRefId":
"739764660256899136"},"mapCoordinate":{"x":106.88582,"y":70.93849,"z":0.0,"unit":"FEET"},
"detectedLocation":null,"configuredLocation":null,"lastUpdatedTime":1466012481898},
{"macAddress":"c8:69:cd:50:29:de","name":null,"type":"Rogue","detectedOn":1465860354185,
"status":"Active","lastUpdatedOn":1466010229973,"currentServerTime":1466016486617,
"expectedHierarchyString":null,"actualHierarchyString":null,"uuid":null,"major":null,
"minor":null,"manufacturerId":null,"rssi":null,"mapInfo":{"mapHierarchyString":
"Singapore>SINGAPORE UE BIZHUB EAST (SNG11)>SNG11-5Fl>MainDemo Theater,SingZone",
"floorRefId":"739764660256899136"},"mapCoordinate":{"x":83.58248,"y":96.976616,"z":0.0,
"unit":"FEET"},"detectedLocation":null,"configuredLocation":null,
"lastUpdatedTime":1466010229973}] 

GET: Returns Active Clients Count

Description

This API returns the count of active clients.

HTTP Method

GET

Resource URI

/api/location/v1/clients/count

Requires OAuth

N

Parameters

None.

Content Type

application/json

API History

Table 13. API History

Release

Modification

Cisco CMX Release 10.3

This API is introduced.

GET: Returns All Clients

Description

This API returns all clients.

HTTP Method

GET

Resource URI

/api/location/v1/clients

Requires OAuth

N

Parameters

None.

Content Type

application/json

API History

Table 14. API History

Release

Modification

Cisco CMX Release 10.3

This API is introduced.

GET: Client by macaddress

Description

This API returns the client by passing the MAC Address.

HTTP Method

GET

Resource URI

/api/location/v1/clients/:macaddress

Requires Basic Auth

N

Parameters

Table 15. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

String

pathReplace

Client macaddress

Content Type

application/json

API History

Table 16. API History

Release

Modification

Cisco CMX Release 10.3

This API is introduced.

GET: Compact History of Client by Date, Username

Description

This API returns compact history of client like number of logins and MAC address of device. The parameters given are date and username.

If the same username was used to login at multiple devices, the MAC address of only one of the devices is returned. To return all MAC addresses, set allMacs parameter to true.

HTTP Method

GET

Resource URI

/api/location/v1/historylite/byusername/:username

Requires Basic Auth

N

Parameters

Table 17. Parameter Details

Name

Required

Default

Type

Location

Description

date

Y

—

String

query

Date in format of yyyy/mm/dd

username

Y

—

String

pathReplace

User name.

allMacs

N

—

String

query

Return all macaddresses associated with this Username for given date

Allowed values/formats:

true

false

allResults

N

String

query

Return all results

Allowed values/formats:

true

false

Content Type

application/json

Sample Output

http://<ip-address>/api/location/v1/historylite/byusername/sharangp?date=2017/06/12

{
Count: 591,
Date: "2017/06/12",
Username: "sharangp",
Macaddress: "3c:a9:f4:6c:ee:44"
}

http://<ip-address>/api/location/v1/historylite/byusername/sharangp?date=2017/06/12&allMacs=true

{
Count: 2,
Date: "2017/06/12",
Username: "sharangp",
Macaddress: [
"3c:a9:f4:6c:4c:7c",
"3c:a9:f4:6c:ee:44"
]
}

GET: Unique MAC Address Seen on a Given Day on a Floor or Zone

Description

This API returns the unique MAC address seen on a given date on a floor or zone. It expects parameters, date and hierarchy. Hierarchy can be up to floor level or zone level. For example, floor level would include: campus-name, building-name, and floor-name. Zone level would be campus-name, building-name, floor-name, and zone-name. If you know the floor ID or the zone ID, then hierarchy is optional and you can specify date and floor ID or date and zone ID parameters.

When the date parameter is not specified, the API would use current date as default. Specifying either of the parameters like hierarchy or floor ID or zone ID is mandatory. This API also supports filter by time and filter by distance criteria. For filtering by time, use fromHour and toHour (both in 24 hr format) parameters. For filtering by distance queries, using filtering by time is mandatory and only a difference of one hour is allowed between toHour and fromHour is one hour.

For example:

By hierarchy: /api/location/v1/history/uniqueclientsbyhierarchy?hierarchy=System%20Campus/Floor-19/1st%20Floor. Floor ID:/api/location/v1/history/uniqueclientsbyhierarchy?floorid=730297895206534073.

By zoneid and date:/api/location/v1/history/uniqueclientsbyhierarchy?zoneid=23 and date=2016/02/29. By hierarchy and filter by time: /api/location/v1/history/uniqueclientsbyhierarchy?hierarchy=System%20Campus/BGLD-19/1st%20Floor and fromHour=13 and toHour=14.

By hierarchy, filter by time and filter by distance: /api/location/v1/history/uniqueclientsbyhierarchy?hierarchy=System%20Campus/BGLD-19/1st%20Floor and fromHour=13 and toHour=14 and x=30 and y=50 and distance=10.

HTTP Method

GET

Resource URI

/api/location/v1/history/uniqueclientsbyhierarchy

Requires Basic Auth

N

Parameters

Table 18. Parameter Details

Name

Required

Default

Type

Location

Description

hierarchy

Y

—

String

query

Hierarchy in format campus-name/building-name/floor-name.

date

N

—

String

query

Date in format of yyyy/mm/dd.

floorid

N

—

String

query

Floor ID.

zoneid

N

—

String

query

Zone ID.

fromHour

N

—

String

query

FromHour, HH in 24 hour format.

toHour

N

—

String

query

ToHour, HH in 24 hour format

x

N

—

String

query

x

y

N

—

String

query

y

distance

N

—

String

query

Distance in feet

Content Type

application/json

GET: Compact History of Client By Date and IPv4 Address

Description

This API returns compact history of client by date and IPv4 address.

HTTP Method

GET

Resource URI

/api/location/v1/historylite/byipaddress/:ipv4address

Requires Basic Auth

N

Parameters

Table 19. Parameter Details

Name

Required

Default

Type

Location

Description

date

Y

—

String

query

Date in format of yyyy/mm/dd.

ipv4address

Y

—

String

pathReplace

IPv4 Address.

Content Type

application/json

Sample Output

http://10.68.40.131/api/location/v1/historylite/byipaddress/10.68.41.186

{
    "Macaddress": null,
    "Ipv4address": "10.22.243.125",
    "Data": [],
    "Count": 0,
    "Date": "2018/07/13"
}

GET: All Client History

Description

This API returns the history of all active clients. This does not include sleeping static devices that do not send probes. It does not support pagination, but you can extract small chunks of data by specifying parameters locatedAfterTime and locatedBeforeTime (in milliseconds).

This API would use the current date as date range from midnight to current time: /api/location/v1/history/clients. This would use the passed date as date range from passed date + fromHour to passed date + toHour: /api/location/v1/history/clients?date=2016/03/02 and fromHour=14 and toHour=15. This would use the date range as mentioned by parameters: locatedAfterTime (1456894800000) milliseconds equivalent to YYYY/MM/DD HH:MM:SS 2016/03/01 21:00:00. locatedBeforeTime (1456896600000) milliseconds equivalent to YYYY/MM/DD HH:MM:SS 2016/03/01 21:30:00: /api/location/v1/history/clients?locatedAfterTime=1456894800000 and locatedBeforeTime=1456896600000.

With CSCuz69078, when locatedAfterTime and locatedBeforeTime specified in API is more than a day and less than an hour, the API returns the following error.

ERROR - Cassandra timeout during read query at consistency ONE (1 responses were required but only 0 replica responded)

For example, https://<ip-address</api/location/v1/history/clients?locatedAfterTime=1459468800000&locatedBeforeTime=1459636800000 returns the ERROR.

This API response returns a maximum of 5000 records without pagination and is sorted based by the MAC address. Therefore, without using the parameters such as locatedAfterTime and locatedBeforeTime to limit the number of records of a specific MAC Address, the API response for client history will return only one MAC Address. The sort order should be by date/time of occurrence.


Note

  • This API can only support queries when the number of clients is less than 5000 per minute.

  • Do not use this API if there are more than 2000 records. For larger datasets, it is recommended to use Northbound Notifications.


HTTP Method

GET

Resource URI

/api/location/v1/history/clients

Requires OAuth

N

Parameters

None.

Content Type

application/json

Sample Output (JSON)

[
    {
        "macAddress": "ac:cf:85:29:53:5f",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor",
            "mapHierarchyDetails": {
                "campus": "Nortech Campus",
                "building": "Nortech-1",
                "floor": "1st Floor",
                "floorAesUid": 727035700041482200,
                "zones": ""
            }
        },
        "mapCoordinate": {
            "x": 78.017624,
            "y": 38.217056,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 160,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-06T22:31:17.730-0800",
            "firstLocatedTime": "2017-12-06T12:57:13.469-0800",
            "lastLocatedTime": "2017-12-06T12:57:13.469-0800"
        },
        "historyLogReason": "FLOOR_CHANGE",
        "geoCoordinate": {
            "latitude": 37.42248685324713,
            "longitude": -121.95989831612766,
            "unit": "DEGREES"
        },
        "rawLocation": null,
        "networkStatus": "ACTIVE",
        "changedOn": 1512593833469,
        "ipAddress": [],
        "userName": "",
        "ssId": "",
        "sourceTimestamp": "1512593833469",
        "band": "UNKNOWN",
        "apMacAddress": "",
        "dot11Status": "UNKNOWN",
        "manufacturer": "HUAWEI TECHNOLOGIES CO.,LTD",
        "areaGlobalIdList": null,
        "detectingControllers": "10.22.243.211",
        "bytesSent": 0,
        "bytesReceived": 0,
        "guestUser": false
    },
    {
        "macAddress": "08:cc:68:b4:1c:1f",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor>CMX Clinic",
            "mapHierarchyDetails": {
                "campus": "Nortech Campus",
                "building": "Nortech-1",
                "floor": "1st Floor",
                "floorAesUid": 727035700041482200,
                "zones": "CMX Clinic"
            }
        },
        "mapCoordinate": {
            "x": 22.515627,
            "y": 15.5579815,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 32,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-06T22:31:17.731-0800",
            "firstLocatedTime": "2017-12-06T19:09:30.430-0800",
            "lastLocatedTime": "2017-12-06T19:09:30.430-0800"
        },
        "historyLogReason": "NETWORK_STATUS_CHANGE",
        "geoCoordinate": {
            "latitude": 37.42242376668243,
            "longitude": -121.95969870663463,
            "unit": "DEGREES"
        },
        "rawLocation": null,
        "networkStatus": "ACTIVE",
        "changedOn": 1512616170430,
        "ipAddress": [],
        "userName": "",
        "ssId": "",
        "sourceTimestamp": "1512616170430",
        "band": "UNKNOWN",
        "apMacAddress": "",
        "dot11Status": "UNKNOWN",
        "manufacturer": "Cisco Systems, Inc",
        "areaGlobalIdList": null,
        "detectingControllers": "10.22.243.211",
        "bytesSent": 0,
        "bytesReceived": 0,
        "guestUser": false
    },
    {
        "macAddress": "08:cc:68:b4:1c:1f",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor>CMX Clinic",
            "mapHierarchyDetails": {
                "campus": "Nortech Campus",
                "building": "Nortech-1",
                "floor": "1st Floor",
                "floorAesUid": 727035700041482200,
                "zones": "CMX Clinic"
            }
        },
        "mapCoordinate": {
            "x": 21.428608,
            "y": 16.509167,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": false,
        "confidenceFactor": 48,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-06T22:31:17.731-0800",
            "firstLocatedTime": "2017-12-06T19:09:03.079-0800",
            "lastLocatedTime": "2017-12-06T19:09:05.082-0800"
        },
        "historyLogReason": "NETWORK_STATUS_CHANGE",
        "geoCoordinate": {
            "latitude": 37.422426413833385,
            "longitude": -121.95969480129244,
            "unit": "DEGREES"
        },
        "rawLocation": null,
        "networkStatus": "INACTIVE",
        "changedOn": 1512616145082,
        "ipAddress": [],
        "userName": "",
        "ssId": "",
        "sourceTimestamp": "1512616145082",
        "band": "UNKNOWN",
        "apMacAddress": "",
        "dot11Status": "UNKNOWN",
        "manufacturer": "Cisco Systems, Inc",
        "areaGlobalIdList": null,
        "detectingControllers": "10.22.243.211",
        "bytesSent": 0,
        "bytesReceived": 0,
        "guestUser": false
    }
]

GET: Compact History of Client by MAC Address

Description

This API returns the history of an active client by its MAC address.

HTTP Method

GET

Resource URI

/api/location/v1/history/clients/:macaddress

Requires OAuth

N

Parameters

Table 20. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

—

String

pathReplace

Client Macaddress.

date

Y

—

String

query

Date in format of yyyy/mm/dd.

Content Type

application/json

Sample Output (JSON)

[
    {
        "macAddress": "98:01:a7:de:cd:35",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor>CMX Clinic",
            "mapHierarchyDetails": {
                "campus": "Nortech Campus",
                "building": "Nortech-1",
                "floor": "1st Floor",
                "floorAesUid": 727035700041482200,
                "zones": "CMX Clinic"
            }
        },
        "mapCoordinate": {
            "x": 26.908728,
            "y": 14.038175,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 16,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-06T22:41:49.631-0800",
            "firstLocatedTime": "2017-12-06T12:19:31.509-0800",
            "lastLocatedTime": "2017-12-06T22:41:48.696-0800"
        },
        "historyLogReason": "DISTANCE_CHANGE",
        "geoCoordinate": {
            "latitude": 37.422419537914266,
            "longitude": -121.9597144965198,
            "unit": "DEGREES"
        },
        "rawLocation": null,
        "networkStatus": "ACTIVE",
        "changedOn": 1512628908696,
        "ipAddress": [],
        "userName": "",
        "ssId": "",
        "sourceTimestamp": "1512628908696",
        "band": "UNKNOWN",
        "apMacAddress": "",
        "dot11Status": "UNKNOWN",
        "manufacturer": "Apple, Inc.",
        "areaGlobalIdList": null,
        "detectingControllers": "10.22.243.211",
        "bytesSent": 0,
        "bytesReceived": 0,
        "guestUser": false
    },
    {
        "macAddress": "98:01:a7:de:cd:35",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor",
            "mapHierarchyDetails": {
                "campus": "Nortech Campus",
                "building": "Nortech-1",
                "floor": "1st Floor",
                "floorAesUid": 727035700041482200,
                "zones": ""
            }
        },
        "mapCoordinate": {
            "x": 25.287996,
            "y": 25.027487,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 24,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-06T22:41:49.632-0800",
            "firstLocatedTime": "2017-12-06T12:19:31.509-0800",
            "lastLocatedTime": "2017-12-06T22:41:46.346-0800"
        },
        "historyLogReason": "DISTANCE_CHANGE",
        "geoCoordinate": {
            "latitude": 37.42245012473281,
            "longitude": -121.9597087015209,
            "unit": "DEGREES"
        },
        "rawLocation": null,
        "networkStatus": "ACTIVE",
        "changedOn": 1512628906346,
        "ipAddress": [],
        "userName": "",
        "ssId": "",
        "sourceTimestamp": "1512628906346",
        "band": "UNKNOWN",
        "apMacAddress": "",
        "dot11Status": "UNKNOWN",
        "manufacturer": "Apple, Inc.",
        "areaGlobalIdList": null,
        "detectingControllers": "10.22.243.211",
        "bytesSent": 0,
        "bytesReceived": 0,
        "guestUser": false
    },
    {
        "macAddress": "98:01:a7:de:cd:35",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor>CMX Clinic",
            "mapHierarchyDetails": {
                "campus": "Nortech Campus",
                "building": "Nortech-1",
                "floor": "1st Floor",
                "floorAesUid": 727035700041482200,
                "zones": "CMX Clinic"
            }
        },
        "mapCoordinate": {
            "x": 26.385386,
            "y": 18.708204,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 16,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-06T22:41:49.632-0800",
            "firstLocatedTime": "2017-12-06T12:19:31.509-0800",
            "lastLocatedTime": "2017-12-06T22:40:44.342-0800"
        },
        "historyLogReason": "DISTANCE_CHANGE",
        "geoCoordinate": {
            "latitude": 37.42243253617424,
            "longitude": -121.95971262854559,
            "unit": "DEGREES"
        },
        "rawLocation": null,
        "networkStatus": "ACTIVE",
        "changedOn": 1512628844342,
        "ipAddress": [],
        "userName": "",
        "ssId": "",
        "sourceTimestamp": "1512628844342",
        "band": "UNKNOWN",
        "apMacAddress": "",
        "dot11Status": "UNKNOWN",
        "manufacturer": "Apple, Inc.",
        "areaGlobalIdList": null,
        "detectingControllers": "10.22.243.211",
        "bytesSent": 0,
        "bytesReceived": 0,
        "guestUser": false
    },
    {
        "macAddress": "98:01:a7:de:cd:35",
        "mapInfo": {
            "mapHierarchyString": "Nortech Campus>Nortech-1>1st Floor>CMX Bar",
            "mapHierarchyDetails": {
                "campus": "Nortech Campus",
                "building": "Nortech-1",
                "floor": "1st Floor",
                "floorAesUid": 727035700041482200,
                "zones": "CMX Bar"
            }
        },
        "mapCoordinate": {
            "x": 28.39643,
            "y": 35.002888,
            "z": 0,
            "unit": "FEET"
        },
        "currentlyTracked": true,
        "confidenceFactor": 24,
        "locComputeType": "RSSI",
        "statistics": {
            "currentServerTime": "2017-12-06T22:41:49.633-0800",
            "firstLocatedTime": "2017-12-06T12:19:31.509-0800",
            "lastLocatedTime": "2017-12-06T22:40:41.877-0800"
        },
        "historyLogReason": "DISTANCE_CHANGE",
        "geoCoordinate": {
            "latitude": 37.4224778909874,
            "longitude": -121.95971990610984,
            "unit": "DEGREES"
        },
        "rawLocation": null,
        "networkStatus": "ACTIVE",
        "changedOn": 1512628841877,
        "ipAddress": [],
        "userName": "",
        "ssId": "",
        "sourceTimestamp": "1512628841877",
        "band": "UNKNOWN",
        "apMacAddress": "",
        "dot11Status": "UNKNOWN",
        "manufacturer": "Apple, Inc.",
        "areaGlobalIdList": null,
        "detectingControllers": "10.22.243.211",
        "bytesSent": 0,
        "bytesReceived": 0,
        "guestUser": false
    }
]

GET: Returns Floor Hierarchy Using MAC Address

Description

This API returns Floor Heirarchy using the MAC address of a client.

HTTP Method

GET

Resource URI

/api/location/v1/compliance/clientcompliance/floor/:macaddr

Requires Basic Auth

N

Parameters

Table 21. Parameter Details

Name

Required

Default

Type

Location

Description

macaddr

Y

String

pathReplace

MAC Addresss of the client

Content Type

application/json

API History

Table 22. API History

Release

Modification

Cisco CMX Reelase 10.3

This command is introduced.

GET: Get Configuration Compliance Rules (By Floor ID)

Description

This API uses the Floor ID to get all configuration compliance rules by floor for client troubleshooting.

HTTP Method

GET

Resource URI

/api/location/v1/compliance/clientcompliance/rules/:floorid

Requires Basic Auth

N

Parameters

Table 23. Parameter Details

Name

Required

Default

Type

Location

Description

floorid

Y

String

pathReplace

Reference id of the floor

Content Type

application/json

API History

Table 24. API History

Release

Modification

Cisco CMX Reelase 10.3

This command is introduced.

GET: Get Configuration Compliance Rules (using MAC Address)

Description

This API uses the MAC address of a client to gets all configuration compliance rules for client-side troubleshooting.

HTTP Method

GET

Resource URI

/api/location/v1/compliance/clientcompliance/rules/mac/:macaddr/:floorid

Requires OAuth

N

Parameters

Table 25. Parameter Details

Name

Required

Default

Type

Location

Description

macaddr

Y

Number

pathReplace

Reference id of the floor

Content Type

application/json

API History

Table 26. API History

Release

Modification

Cisco CMX Reelase 10.3

This command is introduced.

GET: Compact Client History (by Date and Macaddress)

Description

This API returns compact history of client by date and macaddres.

HTTP Method

GET

Resource URI

/api/location/v1/historylite/clients/:macaddress

Requires Basic Auth

N

Parameters

Table 27. Parameter Details

Name

Required

Default

Type

Location

Description

macaddress

Y

String

pathReplace

Client Macaddress

Content Type

application/json

API History

Table 28. API History

Release

Modification

Cisco CMX Release 10.3

This API is introduced.

GET: Get All Configuration Compliance Rules

Description

This API returns all configuration compliance rules for client-side troubleshooting.

HTTP Method

GET

Resource URI

/api/location/v1/compliance/clientcompliance/remediate/:ruleid

Requires Basic Auth

N

Parameters

No Parameters

Content Type

application/json

API History

Table 29. API History

Release

Modification

Cisco CMX Reelase 10.3

This command is introduced.

GET: Tag by MAC Address

Description

This API returns the count of active tags on an array of floors.

HTTP Method

GET

Resource URI

/api/location/v1/tags/multicount

Requires Basic Auth

N

Parameters

None

Content Type

application/json

API History

Table 30. API History

Release

Modification

Cisco CMX Reelase 10.3

This command is introduced.