Skip to end of metadata
Go to start of metadata

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

MARS API Methods

 

This section describes the methods in use with our MARS API.

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Register with MARS, Obtain a MAC Address

 

This method is used to register with MARS and attempt to retrieve the hashed MAC address.

Method

POST

URL

http://localhost:8889/mars-api.phunware.com/v1.1/client

Request Body

Required parameters are underlined.

Parameter

Value

Description

timestamp

string

The date and time in RFC 3339. See MARS API Architecture > Date / Time Format.

schemaVersion

string

Specifies the version of input schema to be used.

device

object

An object containing key-value pairs. Required keys are underlined:

  • deviceId (string): The unique identifier for a registered device.
  • apBSSID (string): The AP BSSID of the Wi-Fi access point. If neither the AP BSSID nor IP address is provided, then service will do a MAC address lookup for a given device ID.
  • ipAddress (string): The device's IP address. If neither the AP BSSID nor IP address is provided, then service will do a MAC address lookup for a given device ID.
  • platformId (string): The OS version. Accepted values: "iOS", "Android"

app

object

An object containing key-value pairs. Required keys are underlined:

  • applicationId (string): The identifier of the MaaS application.
  • venueId (string): The identifier of the venue. Obtained from the mapping API call.
{
    "timestamp": <string>,
    "schemaVersion": <string>,
    "device": 
	{
        "deviceId": <string>,
        "apBSSID": <string>,
        "ipAddress": <string>,
        "platformId": <string>
    },
    "app": 
	{
        "applicationId": <string>,
        "venueId": <string>
    }
}

Example Request

POST the following request body to: http://mars-api.phunware.com/v1.1/client/

{
    "timestamp": "2008-09-08T22:47:31Z",
    "schemaVersion": "1.0",
    "device": 
	{
        //This example is using the Android-formatted device ID.
		//iOS devices use the UUID format for their device IDs.
		//(e.g."25644720-8CED-4E40-96F5-16102F90D2A8") 
		"deviceId": "9161ade538b097cb",
        "apBSSID": "00:11:22:33:44:55:66",
        "ipAddress": "192.168.0.10",
        "platformId": "android"
    },
    "app": 
	{
        "clientId": "244",
        "venueGuid": "7b99ab29-4a74-44f6-b849-8da662205552"
    }
}

Response

A successful response will have a 200 status code and a body containing MAC address data:

{
    "data": 
	{
        "hashedMACAddress": <string>,
        "deviceId": <string>
    }
}

See MARS API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
        "hashedMACAddress": "099a490bfd494a071eea20dd66d5780dd260c7",
        "deviceId": "9161ade538b097cb"
    }
}

Hashing

The device MAC address returned to the client is obfuscated using the HMAC SHA-256 algorithm.

ON THIS PAGE

 

 

 

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Deliver the MAC Address to the MARS Server

 

This method is issued by Cisco MSE to deliver MAC address to MARS server.

When a user requests a new venue to be added via the MaaS portal, the portal will generate two different endpoints: a registration endpoint and notifications endpoint.

Method

POST

URL

http://localhost:8889/mars-api.phunware.com/v1.1/api/southbound/[guid]

Request Bodies

Request body payloads will depend upon the Cisco MSE message type being created:

Example Requests

POST the request body to: http://localhost:8889/mars-api.phunware.com/v1.1/api/southbound/6178e93f51604e349f6f8daa10d40dd4106d37bf

Example request bodies for the different Cisco MSE message types can be found here:

Response

A success response will return a 200 status code with no data in the body of the response. See MARS API Response Handling for error payloads.

ON THIS PAGE

 

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

AssociationEvent Request Body

This page is a continuation of the Request Bodies section of the Deliver the MAC Address to the MARS Server method.

Request body payloads will depend upon the Cisco MSE message type being created:

The following fields exist within a nested AssociationEvent object. Required fields are underlined.

v.7

v.8

Parameter

Value

Description

X

X

subscriptionName

string

The name of the events subscription.

X

X

entity

string

The source agent of the events.

X

X

deviceId

string

The device's MAC address.

 

X

confidenceFactor

float

A numeric value from 0-100 indicating the percent accuracy of the location coordinate returned.

X

X

locationMapHierarchy

string

A concatenation of the campus name, building name and floor name separated by the '>' character. Used to identify the floor uniquely (e.g. "Phunware_Austin>South>1st_Floor").

X

X

locationCoordinate

object

An object containing key / value pairs of location coordinate data:

  • x (float): The x-coordinate of the location.
  • y (float): The y-coordinate of the location.
  • unit (string): The unit of measurement (e.g. "FEET").

 

X

mseUdi

string

The unique Cisco MSE ID.

X

X

geoCoordinate

object

An object containing key / value pairs of geographical coordinate data:

MSE 7 accepts "lattitude" [sic] while MSE 8 accepts "latitude".

  • lat[t]itude (float): The latitude coordinate of the location, in decimal degrees.
  • longitude (float): The longitude coordinate of the location, in decimal degrees.
  • unit (string): The unit of measurement (e.g. "DEGREES").

 

X

floorRefId

integer

The unique ID for a floor object in the Cisco MSE database.

X

X

association

Boolean

Indicates whether the mobile device is associated with the access point.

X

X

ipAddress

array

An array of device IP addresses, as strings.

X

X

apMacAddress

string

The AP MAC Address of the Wi-Fi access point. If neither the AP MAC address nor IP address is provided, then service will do a device ID lookup for a given MAC address.

 

X

status

integer

A numeric value indicating the client's association status. Accepted values: 3 (for Associated) and 7 (for Probing)

 

X

username

string

Username of client in username-based service set identifiers (SSIDs) or a Wi-Fi network name.

 

X

ssid

string

The name of the SSID the client device is connected to (e.g. "Guest Wi-Fi").

 

X

band

string

The GHz band at which the access point received a client probe. It is usually 2.4 or 5 GHz.

 

X

dot11Status

string

A string indicating the client's association status. Accepted values: "ASSOCIATED", "PROBING", "DELETED"

 

X

guestUser

Boolean

Indicates whether the connected device is a guest user.

X

X

timestamp

string

The date and time in RFC 3339.

MSE 7 Payload

For version 7 of MSE, construct the following payload:

{
    "AssociationEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "locationMapHierarchy": <string>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "geoCoordinate": 
		{
            "lattitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "timestamp": <string>,
        "association": <Boolean>,
        "apMacAddress": <string>,
        "ipAddress": 
		[
            <string>,
            <string>
        ]
    }
}

MSE 8 Payload

For version 8 of MSE, construct the following payload:

{
    "AssociationEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "confidenceFactor": <float>,
        "locationMapHierarchy": <string>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "mseUdi": <string>,
        "geoCoordinate": 
		{
            "latitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "floorRefId": <integer>,
        "association": <Boolean>,
        "ipAddress": 
		[
            <string>,
            <string>
        ],
        "apMacAddress": <string>,
        "status": <integer>,
        "username": <string>,
        "ssid": <string>,
        "band": <string>,
        "dot11Status": <string>,
        "guestUser": <Boolean>,
        "timestamp": <string>
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

AssociationEvent Example Requests

 

This page is a continuation of the Example Requests section of the Deliver the MAC Address to the MARS Server method.

POST the request body to: http://localhost:8889/mars-api.phunware.com/v1.1/api/southbound/6178e93f51604e349f6f8daa10d40dd4106d37bf

Example request bodies for the other Cisco MSE message types can be found here:

MSE 7

For version 7 of MSE, construct the following payload:

{
    "AssociationEvent": 	
	{
        "subscriptionName": "CMX_Association_Event",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "18:af:61:51:6c:77",
        "locationMapHierarchy": "Phunware_Austin>South>1st_Floor",
        "locationCoordinate": 
		{
            "x": 90.64,
            "y": 80.26,
            "unit": "FEET"
        },
        "geoCoordinate": 
		{
            "lattitude": 33.6600694426,
            "longitude": -117.8614988409,
            "unit": "DEGREES"
        },
        "timestamp": "2014-02-18T20:02:41.218+0000",
        "association": true,
        "apMacAddress": "e8:ed:f3:1b:2e:60",
        "ipAddress": 
		[
            "10.180.181.99",
            "fe80:0000:0000:0000:10c9:596b:3448:1797"
        ]
    }
}

MSE 8

For version 8 of MSE, construct the following payload:

{
    "AssociationEvent": 
	{
        "subscriptionName": "CMX_Association_Event",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "18:af:61:51:6c:77",
        "confidenceFactor": 64.0,
        "locationMapHierarchy": "Phunware_Austin>South>1st_Floor",
        "locationCoordinate": 
		{
            "x": 90.64,
            "y": 80.26,
            "unit": "FEET"
        },
        "mseUdi": "AIR-MSE-VA-K9:V01:att-corpmse01.phunware.com_31b",
        "geoCoordinate": 
		{
            "latitude": 33.6600694426,
            "longitude": -117.8614988409,
            "unit": "DEGREES"
        },
        "floorRefId": 748833797235015762,
        "association": true,
        "ipAddress": 
		[
            "10.180.181.99",
            "fe80:0000:0000:0000:10c9:596b:3448:1797"
        ],
        "apMacAddress": "e8:ed:f3:1b:2e:60",
        "status": 3,
        "username": "",
        "ssid": Phunware,
        "band": "5.0",
        "dot11Status": "ASSOCIATED",
        "guestUser": false,
        "timestamp": "2014-02-18T20:02:41.218+0000"
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

ContainmentEvent Request Body

 

This page is a continuation of the Request Bodies section of the Deliver the MAC Address to the MARS Server method.

Request body payloads will depend upon the Cisco MSE message type being created:

The following fields exist within a nested ContainmentEvent object. Required fields are underlined.

v.7

v.8

Parameter

Value

Description

X

X

subscriptionName

string

The name of the events subscription.

X

X

entity

string

The source agent of the events.

X

X

deviceId

string

The device's MAC address.

 

X

confidenceFactor

float

A numeric value from 0-100 indicating the percent accuracy of the location coordinate returned.

X

X

locationCoordinate

object

An object containing key / value pairs of location coordinate data:

  • x (float): The x-coordinate of the location.
  • y (float): The y-coordinate of the location.
  • unit (string): The unit of measurement (e.g. "FEET").

 

X

mseUdi

string

The unique Cisco MSE ID.

X

X

geoCoordinate

object

An object containing key / value pairs of geographical coordinate data:

MSE 7 accepts "lattitude" [sic] while MSE 8 accepts "latitude".

  • lat[t]itude (float): The latitude coordinate of the location, in decimal degrees.

  • longitude (float): The longitude coordinate of the location, in decimal degrees.
  • unit (string): The unit of measurement (e.g. "DEGREES").

 

X

floorRefId

integer

The unique ID for a floor object in the Cisco MSE database.

X

X

boundary

string

Defines if the user was "INSIDE" or "OUTSIDE" of a target area during a breach. The MARS API only uses floor breaches, so this always returns "INSIDE".

X

X

areaType

string

The location object a client device was seen on. Accepted values: "CAMPUS", "BUILDING", "FLOOR" and "ZONE". The MARS API only uses floor breaches, so this always returns "FLOOR".

X

X

containerHierarchy

string

A concatenation of the campus name, building name and floor name a device was seen on, separated by the '>' character. Used to identify the floor uniquely (e.g. "Phunware_Austin>South>1st_Floor").

X

X

timestamp

string

The date and time in RFC 3339.

MSE 7 Payload

For version 7 of MSE, construct the following payload:

{
    "ContainmentEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "geoCoordinate": 
		{
            "lattitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "boundary": <string>,
        "areaType": <string>,
        "containerHierarchy": <string>,
        "timestamp": <string>
    }
}

MSE 8 Payload

For version 8 of MSE, construct the following payload:

{
    "ContainmentEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "confidenceFactor": <float>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "mseUdi": <string>,
        "floorRefId": <integer>,
        "boundary": <string>,
        "areaType": <string>,
        "geoCoordinate": 
		{
            "latitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "containerHierarchy": <string>,
        "timestamp": <string>
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

ContainmentEvent Example Requests

 

This page is a continuation of the Example Requests section of the Deliver the MAC Address to the MARS Server method.

POST the request body to: http://localhost:8889/mars-api.phunware.com/v1.1/api/southbound/6178e93f51604e349f6f8daa10d40dd4106d37bf

Example request bodies for the other Cisco MSE message types can be found here:

MSE 7

For version 7 of MSE, construct the following payload:

{
    "ContainmentEvent": 
	{
        "subscriptionName": "CMX_Containment_Event",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "fc:c2:de:9d:58:62",
        "locationCoordinate": 
		{
            "x": 254.4425,
            "y": 70.65469,
            "unit": "FEET"
        },
        "geoCoordinate": 
		{
            "lattitude": 37.405174727690955,
            "longitude": -121.97659694880194,
            "unit": "DEGREES"
        },
        "boundary": "INSIDE",
        "areaType": "FLOOR",
        "containerHierarchy": "Phunware_Austin>South>1st_Floor",
        "timestamp": "2014-10-10T07:41:58.710-0700"
    }
}

MSE 8

For version 8 of MSE, construct the following payload:

{
    "ContainmentEvent": 
	{
        "subscriptionName": "CMX_Containment_Event",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "fc:c2:de:9d:58:62",
        "confidenceFactor": 24,
        "locationCoordinate": 
		{
            "x": 254.4425,
            "y": 70.65469,
            "unit": "FEET"
        },
        "mseUdi": "AIR-MSE-VA-K9:V01:MSE-VA-77_32af66dc-bb7b-11e3",
        "floorRefId": 4698041219291283000,
        "boundary": "INSIDE",
        "areaType": "FLOOR",
        "geoCoordinate": 
		{
            "latitude": 37.405174727690955,
            "longitude": -121.97659694880194,
            "unit": "DEGREES"
        },
        "containerHierarchy": "Phunware_Austin>South>1st_Floor",
        "timestamp": "2014-10-10T07:41:58.710-0700"
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

AbsenceEvent Request Body

 

This page is a continuation of the Request Bodies section of the Deliver the MAC Address to the MARS Server method.

Request body payloads will depend upon the Cisco MSE message type being created:

The following fields exist within a nested AbsenceEvent object. Required fields are underlined. 

v.7

v.8

Parameter

Value

Description

X

X

subscriptionName

string

The name of the events subscription.

X

X

entity

string

The source agent of the events.

X

X

deviceId

string

The device's MAC address.

 

X

confidenceFactor

float

A numeric value from 0-100 indicating the percent accuracy of the location coordinate returned.

X

X

locationMapHierarchy

string

A concatenation of the campus name, building name and floor name separated by the '>' character. Used to identify the floor uniquely (e.g. "Phunware_Austin>South>1st_Floor").

X

X

locationCoordinate

object

An object containing key / value pairs of location coordinate data:

  • x (float): The x-coordinate of the location.
  • y (float): The y-coordinate of the location.
  • unit (string): The unit of measurement (e.g. "FEET").

 

X

mseUdi

string

The unique Cisco MSE ID.

X

X

geoCoordinate

object

An object containing key / value pairs of geographical coordinate data:

MSE 7 accepts "lattitude" [sic] while MSE 8 accepts "latitude".

  • lat[t]itude (float): The latitude coordinate of the location, in decimal degrees.

  • longitude (float): The longitude coordinate of the location, in decimal degrees.
  • unit (string): The unit of measurement (e.g. "DEGREES").

 

X

floorRefId

integer

The unique ID for a floor object in the Cisco MSE database.

X

X

absenceDurationInMinutes

integer

The number of minutes since the user's device was last seen by the MSE.

X

X

lastSeen

string

The timestamp at which the MSE last saw the client device.

X

X

timestamp

string

The date and time in RFC 3339.

MSE 7 Payload

For version 7 of MSE, construct the following payload:

{
    "AbsenceEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "locationMapHierarchy": <string>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "absenceDurationInMinutes": <integer>,
        "geoCoordinate": 
		{
            "lattitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "lastSeen": <string>,
        "timestamp": <string>
    }
}

MSE 8 Payload

For version 8 of MSE, construct the following payload:

{
    "AbsenceEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "confidenceFactor": <float>,
        "locationMapHierarchy": <string>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "mseUdi": <string>,
        "geoCoordinate": 
		{
            "latitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "floorRefId": <integer>,
        "absenceDurationInMinutes": <integer>,
        "lastSeen": <string>,
        "timestamp": <string>
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

AbsenceEvent Example Requests

 

This page is a continuation of the Example Requests section of the Deliver the MAC Address to the MARS Server method.

POST the request body to: http://localhost:8889/mars-api.phunware.com/v1.1/api/southbound/6178e93f51604e349f6f8daa10d40dd4106d37bf

Example request bodies for the other Cisco MSE message types can be found here:

MSE 7

For version 7 of MSE, construct the following payload:

{
    "AbsenceEvent": 
	{
        "subscriptionName": "CMX_Absence_Event",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "9c:04:eb:a5:94:49",
        "locationMapHierarchy": "Phunware_Austin>South>1st_Floor",
        "locationCoordinate": 
		{
            "x": 223.45,
            "y": 23.44,
            "unit": "FEET"
        },
        "absenceDurationInMinutes": 30,
        "geoCoordinate":
		{
            "lattitude": 30.3598096444,
            "longitude": -97.7419564503,
            "unit": "DEGREES"
        },
        "lastSeen": "2014-10-10T14:23:40.539+0000",
        "timestamp": "2014-10-10T14:54:10.540+0000"
    }
}

MSE 8

For version 8 of MSE, construct the following payload:

{
    "AbsenceEvent": 
	{
        "subscriptionName": "CMX_Absence_Event",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "9c:04:eb:a5:94:49",
        "confidenceFactor": 50,
        "locationMapHierarchy": "Phunware_Austin>South>1st_Floor",
        "locationCoordinate": 
		{
            "x": 223.45,
            "y": 23.44,
            "unit": "FEET"
        },
        "mseUdi": "AIR-MSE-VA-K9:V01:att-corpmse01.phunware.com_31b",
        "geoCoordinate": 
		{
            "latitude": 30.3598096444,
            "longitude": -97.7419564503,
            "unit": "DEGREES"
        },
        "floorRefId": 748833797235015700,
        "absenceDurationInMinutes": 30,
        "lastSeen": "2014-10-10T14:23:40.539+0000",
        "timestamp": "2014-10-10T14:54:10.540+0000"
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

MovementEvent Request Body

 

This page is a continuation of the Request Bodies section of the Deliver the MAC Address to the MARS Server method.

Request body payloads will depend upon the Cisco MSE message type being created:

The following fields exist within a nested MovementEvent object. Required fields are underlined. 

v.7

v.8

Parameter

Value

Description

X

X

subscriptionName

string

The name of the events subscription.

X

X

entity

string

The source agent of the events.

X

X

deviceId

string

The device's MAC address.

 

X

confidenceFactor

float

A numeric value from 0-100 indicating the percent accuracy of the location coordinate returned.

X

X

locationMapHierarchy

string

A concatenation of the campus name, building name and floor name separated by the '>' character. Used to identify the floor uniquely (e.g. "Phunware_Austin>South>1st_Floor".

X

X

locationCoordinate

object

An object containing key / value pairs of location coordinate data:

  • x (float): The x-coordinate of the location.
  • y (float): The y-coordinate of the location.
  • unit (string): The unit of measurement (e.g. "FEET").

 

X

mseUdi

string

The unique Cisco MSE ID.

X

X

geoCoordinate

object

An object containing key / value pairs of geographical coordinate data:

MSE 7 accepts "lattitude" [sic] while MSE 8 accepts "latitude".

  • lat[t]itude (float): The latitude coordinate of the location, in decimal degrees.

  • longitude (float): The longitude coordinate of the location, in decimal degrees.
  • unit (string): The unit of measurement (e.g. "DEGREES").

 

X

floorRefId

integer

The unique ID for a floor object in the Cisco MSE database.

X

X

moveDistanceInFeet

integer

The displacement of the client device from the last reported X&Y coordinate.

 

X

currentlyTracked

Boolean

Indicates whether the MSE is sending MovementEvents for the associated client device.

 

X

ipAddress

array

An array of device IP addresses, as strings.

 

X

ssid

string

The name of the SSID the client device is connected to (e.g. "Guest Wi-Fi").

 

X

band

string

The GHz band at which the access point received a client probe. It is usually 2.4 or 5 GHz.

 

X

dot11Status

string

A string indicating the client's association status. Accepted values: "ASSOCIATED", "PROBING", "DELETED"

 

X

apMacAddress

string

The AP MAC Address of the Wi-Fi access point. If neither the AP MAC address nor IP address is provided, then service will do a device ID lookup for a given MAC address.

 

X

guestUser

Boolean

Indicates whether the connected device is a guest user.

X

X

timestamp

string

The date and time in RFC 3339.

MSE 7 Payload

For version 7 of MSE, construct the following payload:

{
    "MovementEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "locationMapHierarchy": <string>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "geoCoordinate": 
		{
            "lattitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "moveDistanceInFt": <float>,
        "timestamp": <string>
    }
}

MSE 8 Payload

For version 8 of MSE, construct the following payload:

{
    "MovementEvent": 
	{
        "subscriptionName": <string>,
        "entity": <string>,
        "deviceId": <string>,
        "confidenceFactor": <float>,
        "locationMapHierarchy": <string>,
        "locationCoordinate": 
		{
            "x": <float>,
            "y": <float>,
            "unit": <string>
        },
        "mseUdi": <string>,
        "floorRefId": <integer>,
        "moveDistanceInFt": <float>,
        "currentlyTracked": <Boolean>,
        "ipAddress": 
		[
            <string>,
            <string>
        ],
        "ssid": <string>,
        "band": <string>,
        "dot11Status": <string>,
        "apMacAddress": <string>,
        "guestUser": <Boolean>,
        "geoCoordinate": 
		{
            "latitude": <float>,
            "longitude": <float>,
            "unit": <string>
        },
        "timestamp": <string>
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

MovementEvent Example Requests

 

This page is a continuation of the Example Requests section of the Deliver the MAC Address to the MARS Server method.

POST the request body to: http://localhost:8889/mars-api.phunware.com/v1.1/api/southbound/6178e93f51604e349f6f8daa10d40dd4106d37bf

Example request bodies for the other Cisco MSE message types can be found here:

MSE 7

For version 7 of MSE, construct the following payload:

{
    "MovementEvent": 
	{
        "subscriptionName": "CMX_Location_Event_PROD_NEW",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "cc:3a:61:27:1c:d2",
        "locationMapHierarchy": "Phunware_Austin>South>1st_Floor",
        "locationCoordinate": 
		{
            "x": 23.415796,
            "y": 43.35957,
            "unit": "FEET"
        },
        "geoCoordinate": 
		{
            "lattitude": 30.359974591172836,
            "longitude": -97.74253279388846,
            "unit": "DEGREES"
        },
        "moveDistanceInFt": 32.533466,
        "timestamp": "2014-10-10T14:53:25.482+0000"
    }
}

MSE 8

For version 8 of MSE, construct the following payload:

{
    "MovementEvent": 
	{
        "subscriptionName": "CMX_Location_Event_PROD_NEW",
        "entity": "WIRELESS_CLIENTS",
        "deviceId": "cc:3a:61:27:1c:d2",
        "confidenceFactor": 75.0,
        "locationMapHierarchy": "Phunware_Austin>South>1st_Floor",
        "locationCoordinate": 
		{
            "x": 23.415796,
            "y": 43.35957,
            "unit": "FEET"
        },
        "mseUdi": "AIR-MSE-VA-K9:V01:att-corpmse01.phunware.com_31b",
        "floorRefId": 748833797235015743,
        "moveDistanceInFt": 32.533466,
        "currentlyTracked": true,
        "ipAddress": 
		[
            "10.180.181.99",
            "fe80:0000:0000:0000:10c9:596b:3448:1797"
        ],
        "ssid": Phunware,
        "band": "5.0",
        "dot11Status": "ASSOCIATED",
        "apMacAddress": "e8:ed:f3:1b:2e:60",
        "guestUser": false,
        "geoCoordinate": 
		{
            "latitude": 30.359974591172836,
            "longitude": -97.74253279388846,
            "unit": "DEGREES"
        },
        "timestamp": "2014-10-10T14:53:25.482+0000"
    }
}

ON THIS PAGE

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Register or Update with Cisco MSE

 

This method is used to register or update a Cisco MSE. Given the list of floors, and associated information, this will populate the identified venue's campuses, buildings and floors. The response will then contain API URLs for each map resource that needs to be uploaded.

Method

POST

URL

http://mars-api.phunware.com/v1.1/mse/[guid]/register

Request Body

Required parameters are underlined.

Parameter

Value

Description

floors

array

An array of floor objects containing key-value pairs. Required keys are underlined:

  • name (string): The unique name of the floor.
  • level (integer): The floor level within the building.
  • isOutdoor (Boolean): Indicates whether the floor is outdoor.
  • length (integer): The length of this floor.
  • height (integer): The height of this floor.
  • offsetX (integer): The X offset of the floor within the map image.
  • offsetY (integer): The Y offset of the floor within the map image.
  • textHierarchy (array): An array containing the campus, building and floor name (in that order).
  • imageExists (Boolean): Indicates whether an image exists for this floor. If true, the response will contain an item referencing an API URL where the actual resource data should be posted.
  • imageName (string): The name of the image, if it exists. This is only used to send back in the response.
  • imageType (string): The MIME type of the image, if it exists. This is only used to send back in the response.
{
    "floors": 
	[
        {
            "name": <string>,
            "level": <integer>,
            "isOutdoor": <Boolean>,
            "length": <integer>,
            "height": <integer>,
            "offsetX": <integer>,
            "offsetY": <integer>,
            "textHierarchy": 
			[
                <string>,
                <string>,
                <string>
            ],
            "imageName": <string>,
            "imageType": <string>,
            "imageExists": <Boolean>
        }
    ]
}

Example Request

POST the following request body to: http://mars-api.phunware.com/v1.1/mse/f0685279-7497-4d90-882e-12201e476b0e/register/

{
    "floors": 
	[
        {
            "name": "WNBU",
            "level": 4,
            "isOutdoor": false,
            "length": 185,
            "height": 10,
            "offsetX": 5,
            "offsetY": 0,
            "textHierarchy": 
			[
                "Cisco Site 4",
                "SJ-14",
                "WNBU"
            ],
            "imageName": "domain_0_1349311055718.png",
            "imageType": "image/png",
            "imageExists": true
        }
    ]
} 

Response

A success response will return a 200 status code with no data in the body of the response. See MARS API Response Handling for error payloads.

ON THIS PAGE

 

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Upload Map Image Data for a Floor

 

This method is used to upload the map image data for a particular floor. The request must use "multipart/form-data" as the value for the "Content-Type" header.

Method

POST

URL

http://mars-api.phunware.com/v1.1/mse/[guid]/[floorId]/upload-resource

Request Body

Required parameters are underlined.

Parameter

Value

Description

image

binary

The binary file data.

Example Request

POST
http://mars-api.phunware.com/v1.1/mse/f0685279-7497-4d90-882e-12201e476b0e/17/upload-resource

Response

A success response will return a 200 status code with no data in the body of the response. See MARS API Response Handling for error payloads.

ON THIS PAGE

 

 

 

This documentation is no longer actively supported and may be out of date. Going forward, please visit and bookmark our new site (https://docs.phunware.com/) for up-to-date documentation.

Delete Full Bind Record

 

This method is used to Delete full bind record from Memcache. Whenever a device is not receiving location updates from MSE, you can start troubleshooting by deleting fullbind record associated with that device from Memcache and this is the endpoint you will use for deleting a record from Memcache. This endpoint is used mostly for troubleshooting purposes by SDK team.

Method :

DELETE

URL : 

http://localhost:8889/mars-api.phunware.com/v1.1/bind/[DeviceMacAddr]

Ex : http://localhost:8889/mars-api.phunware.com/v1.1/bind/25:Ge:00:00:00:KP

Response :

A successful response will have a 200 status code and a body containing following message : 

Successfully deleted fullbind record from Memcache

  • No labels