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.

VENUE

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.

Create a Venue

 

This method is used to create a venue and initialize the data structures provided by the Cisco Prime interface.

Method

POST

URL

http://map-api.phunware.com/v1.1/venues

Headers

X-Auth (see Security)

Request Body

Required parameters are underlined.

Parameter

Value

Description

name

string

The name of the venue. We recommend a unique string to help differentiate this venue from other venues.

orgIds

string

The identifiers of the organizations associated with this venue.

isActive

Boolean

Describes whether the venue is active (“true)” or inactive (“false”). A venue is typically set to inactive to indicate that it is being populated or edited. It is also used to indicate that the venue was once active but has since been replaced or is no longer valid.

clientIds

string

The identifiers of the mobile client applications associated with this venue.

mseUdi

string

This is a value that corresponds to a Cisco MSE identifier. It is set during the MSE registration process.

supportsGeographicCoordinates

Boolean

Describes whether this venue supports native mapping (latitude and longitude).

{
    "name": <string>,
    "appId": <string>,
    "clientIds": <string>,
    "orgIds": <string>,
    "isActive": true,
    "mseUdi": <string>,
    "supportsGeographicCoordinates": <Boolean>
}

Example Request

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

{
    "name": "Hyrule",
    "appId": "123456",
    "clientIds": "98765,6543",
    "orgIds": "8,9",
    "mseUdi": "abcd",
    "supportsGeographicCoordinates": true
}

Response

A successful response will have a 200 status code and a body containing the GUID of the newly created venue:

{
    "data": 
	{
        "guid": <string>
    }
}

See Mapping API Response Handling for error payloads.

Example Response

Example body of successful response:

{
    "data": 
	{
        "guid": "f0685279-7497-4d90-882e-12201e476b0e"
    }
}

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.

Retrieve a Venue

 

This method is used to retrieve a venue by venue ID.

Method

GET

URL

http://map-api.phunware.com/v1.1/venues/[guid]

Headers

X-Auth (see Security)

Query Parameters

None

Example Request

GET
http://map-api.phunware.com/v1.1/venues/99869682-f231-462a-a0a5-33067b48bd74

Response

A successful response will have a 200 status code and a body containing an object with venue data:

{
    "guid": <string>,
    "name": <string>,
    "appId": <string>,
    "clientIds": <string>,
    "orgIds": <string>,
    "isActive": <Boolean>,
    "mseUdi": <string>,
    "callbackUrl": <string>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "supportsGeographicCoordinates": <Boolean>,
    "draftStatus": <string>
}

See Mapping API Response Handling for error payloads. 

Example Response

Example body of a successful response:

{
    "guid": "f0685279-7497-4d90-882e-12201e476b0e",
    "name": "Hyrule",
    "appId": "123456",
    "clientIds": "98765,6543",
    "orgIds": "8,9",
    "isActive": true,
    "mseUdi": "abcd",
    "callbackUrl": "http://www.Hyrule.com",
    "createdAt": "2014-06-14T12:21:38Z",
    "updatedAt": "2014-06-14T12:21:38Z",
    "supportsGeographicCoordinates": true,
    "draftStatus": "DRAFT"
}

 

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.

Retrieve a Collection of Venues

 

This method is used to retrieve an array of venues that satisfy search criteria.

Method

GET

URL

http://map-api.phunware.com/v1.1/venues

Headers

X-Auth (see Security)

Query Parameters

Any combination of orgId, isActive and/or clientId is accepted, but at least one must be present or the request is considered a bad request.

Parameter

Value

Description

orgId

integer

The identifier of the organization.

isActive

Boolean

Describes whether to search for active (“true”) or inactive (“false”) venues. Both active and inactive venues will be retrieved by default.

clientId

integer

The identifier of the mobile client application.

Example Query Fragment

{
    "orgId": 12,
    "isActive": true,
    "clientId": 4
} 

URL-encoded, minified fragment:

%7B%22orgId%22%3A%2012%2C%20%22isActive%22%3A%20true%2C%20%22clientId%22%3A%204%7D

Example Request 

GET
http://map-api.phunware.com/v1.1/venues?%7B%22orgId%22%3A%2012%2C%20%22isActive%22%3A%20true%2C%20%22clientId%22%3A%204%7D 

Response

A successful response will have a 200 status code and a body containing an array of venues that satisfy the query parameters:

{
    "data": 
	[
        {
            "guid": <string>,
            "name": <string>,
            "appId": <string>,
            "clientIds": <string>,
            "orgIds": <string>,
            "isActive": <Boolean>,
            "mseUdi": <string>,
            "callbackUrl": <string>,
            "createdAt": <string>,
            "updatedAt": <string>,
            "supportsGeographicCoordinates": <Boolean>
        },
        {
            "guid": <string>,
            "name": <string>,
            "appId": <string>,
            "clientIds": <string>,
            "orgIds": <string>,
            "isActive": <Boolean>,
            "mseUdi": <string>,
            "callbackUrl": <string>,
            "createdAt": <string>,
            "updatedAt": <string>,
            "supportsGeographicCoordinates": <Boolean>,
            "draftStatus": <string>
        },
        ...
    ]
}

See Mapping API Response Handling for error payloads. 

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
            "guid": "00000000-1234-1234-abcd-123456789012",
            "name": "Sacred Realm",
            "appId": "123",
            "clientIds": "2,3,4",
            "orgIds": "12",
            "isActive": true,
            "mseUdi": "mseUdi value",
            "callbackUrl": "http://www.phunware.com",
            "createdAt": "2014-06-14T12:21:38Z",
            "updatedAt": "2014-06-14T12:21:38Z",
            "supportsGeographicCoordinates": true,
            "draftStatus": "DRAFT"
        },
        {
            "guid": "c8647fc7-ff52-4584-8de5-8361160c32e4",
            "name": "Twilight Realm",
            "appId": "456",
            "clientIds": "1,2,3,4",
            "orgIds": "12",
            "isActive": false,
            "mseUdi": "mseUdi value",
            "callbackUrl": "http://www.phunware.com",
            "createdAt": "2014-06-14T12:21:38Z",
            "updatedAt": "2014-06-14T12:21:38Z",
            "supportsGeographicCoordinates": true,
            "draftStatus": "DRAFT"
        }
    ]
}

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.

Update a Venue

 

This method is used to update an existing venue.

Method

PUT

URL

http://map-api.phunware.com/v1.1/venues/[guid]

Headers

X-Auth (see Security)

Request Body

See Mapping API Architecture > PUT Methods & Partial Updates.

Parameter

Value

Description

name

string

The name of the venue. We recommend a unique string to help differentiate this venue from other venues.

orgIds

string

Identifiers of the organizations associated with the venue.

isActive

Boolean

Describes whether the venue is active (“true)” or inactive (“false”). A venue is typically set to inactive to indicate that it is being populated or edited. It is also used to indicate that the venue was once active but has since been replaced or is no longer valid.

clientIds

string

The identifiers of the mobile client applications associated with this venue.

mseUdi

string

This is a value that corresponds to a Cisco MSE identifier. It is set during the MSE registration process.

supportsGeographicCoordinates

Boolean

Describes whether this venue supports native mapping (latitude and longitude).

{
    "orgIds": <string>,
    "isActive": <Boolean>
}

Example Request

PUT the following request body to: http://map-api.phunware.com/v1.1/venues/99869682-f231-462a-a0a5-33067b48bd74

{
    "orgIds": "13,14,15",
    "isActive": false
}

Response

A success response will return a 204 status code with no data in the body of the response. See Mapping 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 a Venue

 

This method is used to delete a venue.

Method

DELETE

URL

http://map-api.phunware.com/v1.1/venues/[guid]

Headers

X-Auth (see Security)

Request Parameters

None

Example Request

DELETE
http://map-api.phunware.com/v1.1/venues/f0685279-7497-4d90-882e-12201e476b0e 

Response

A success response will return a 204 status code with no data in the body of the response. See Mapping 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.

Venue Audit History

 

Any resource (Venue, Campus, Building, Floor, Point, Segment, Resource, etc) that is added, modified, or deleted via the Mapping API should now generate an audit record in the database.  In order to record user ID and username information in the audit history, the following request headers and appropriate values must be passed in each such request:

"userId"

"username"

These  audit history records can be retrieved via the following endpoint:

Method

GET

URL

http://map-api.phunware.com/v1.1/venues/history

Headers

X-Auth (see Security)

userId - string

username - string

Query Parameters

Any combination of orgId, isActive and/or clientId is accepted, but at least one must be present or the request is considered a bad request.

Parameter

Value

Description

venueGuid

string

The unique identifier for the venue.

sinceLastPublish

Boolean

If "true", only the audit history for since the last "publish" operation will be retrieved. If "false" or not specified, all venue history will be retrieved for that venue. It is a bad request error to have both "sinceLastPublish" and "publishesOnly" set to true since they would be in conflict with each other.

publishesOnly

Boolean

If "true", only publish operations will be retrieved. It is a bad request error to have both "sinceLastPublish" and "publishesOnly" set to true since they would be in conflict with each other.

publishIdinteger

If set, only the audit history for a particular publish operation will be retrieved. If a "publishId" is given, then both "sinceLastPublish" and "publishesOnly" must be false or omitted; otherwise it is a bad request error since the query parameters would be in conflict with each other.

Example Query Fragment

{"venueGuid":"f8a2f66c-84e4-4e27-a811-42db9cae8e9a","sinceLastPublish":false}

URL-encoded, minified fragment:

%7B%22venueGuid%22%3A%22f8a2f66c-84e4-4e27-a811-42db9cae8e9a%22%2C%22sinceLastPublish%22%3Afalse%7D

Example Request 

GET
http://map-api.phunware.com/v1.1/venues?%7B%22venueGuid%22%3A%22f8a2f66c-84e4-4e27-a811-42db9cae8e9a%22%2C%22sinceLastPublish%22%3Afalse%7D 

Response

A successful response will have a 200 status code and a body containing an array of audit history records that satisfy the query parameters:

{
    "data": 
	[
        {
          "id": <integer>,
          "userId": <string>,
          "username": <string>,
          "description": <string>,
          "venueGuid": <string>,
          "type": <string>,
          "crud": <string>,
          "elementId": <string>,
          "createdAt": <string>,
          "campusName": <string>,
          "campusId": <integer>,
          "buildingName": <string>,
          "buildingId": <integer>,
          "floorName": <string>,
          "floorId": <integer>
        },
        ...
    ]
}

See Mapping API Response Handling for error payloads. 

Example Response

Example body of a successful response:

{
    "data": 
	[
        {
          "id": 1064,
          "userId": "127",
          "username": "tferguson@abc123.com",
          "description": " added new Venue",
          "venueGuid": "f8a2f66c-84e4-4e27-a811-42db9cae8e9a",
          "type": "Venue",
          "crud": "C",
          "elementId": "f8a2f66c-84e4-4e27-a811-42db9cae8e9a",
          "createdAt": "2015-06-25T07:31:28Z",
          "campusName": null,
          "campusId": 0,
          "buildingName": null,
          "buildingId": 0,
          "floorName": null,
          "floorId": 0
        },
        {
          "id": 1065,
          "userId": "127",
          "username": "tferguson@abc123.com",
          "description": "No changes made",
          "venueGuid": "f8a2f66c-84e4-4e27-a811-42db9cae8e9a",
          "type": "Venue",
          "crud": "U",
          "elementId": "f8a2f66c-84e4-4e27-a811-42db9cae8e9a",
          "createdAt": "2015-06-25T07:31:29Z",
          "campusName": null,
          "campusId": 0,
          "buildingName": null,
          "buildingId": 0,
          "floorName": null,
          "floorId": 0
        }
    ]
}

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.

Workflow - Publish and Revert

 

The only way to modify a “live” venue or any of its child elements is via a publish operation.  This allows better control over who can modify “live” data.

 

Publish

Publishing overwrites the "live" venue with the values in the "draft" venue.  The body of the request must contain the GUID of the draft venue to be published.

Method

PUT

URL

http://map-api.phunware.com/v1.1/venues/published

Headers

X-Auth (see Security)

Query Parameters

None

Request Body

See Mapping API Architecture > PUT Methods & Partial Updates.

Parameter

Value

Description

sourceGuid

string

The GUID of the draft version of the venue, which will be published, overwriting the live version.

   

 

 

{ 
   "sourceGuid": <string>
}

Example Request

PUT the following request body to: http://map-api.phunware.com/v1.1/venues/published

{ 
   "sourceGuid": "432f21fa-b997-436a-ac1a-dafc9406d025"
}

Response

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

{
     "data": {
         "message": <string>
         "guid": <string>
     }
}

 

Example Response

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

{
     "data": {
         "message": "Accepted",
         "guid": "1bff7beb-05b8-4049-854d-137de3e38303"
     }
}

 

 

 

Revert

"Reverting" overwrites the "draft" venue with the values in the "live" venue.  The body of the request must contain the GUID of the live venue to PUT to draft.

Method

PUT

URL

http://map-api.phunware.com/v1.1/venues/draft

Headers

X-Auth (see Security)

Query Parameters

None

Request Body

See Mapping API Architecture > PUT Methods & Partial Updates.

Parameter

Value

Description

sourceGuid

string

The GUID of the live version of the venue, which will be used to overwrite the current draft version

   

 

 

{ 
   "sourceGuid": <string>
}

Example Request

PUT the following request body to: http://map-api.phunware.com/v1.1/venues/published

{ 
   "sourceGuid": "1bff7beb-05b8-4049-854d-137de3e38303"
}

Response

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

{
     "data": {
         "message": <string>
         "guid": <string>
     }
}

 

Example Response

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

{
     "data": {
         "message": "Accepted",
         "guid": "432f21fa-b997-436a-ac1a-dafc9406d025"
     }
}

 

A venue is a location where events take place. Venues consist of one or more campuses.

{
    "guid": <string>,
    "name": <string>,
    "appId": <string>,
    "clientIds": <string>,
    "orgIds": <string>,
    "isActive": <Boolean>,
    "mseUdi": <string>,
    "createdAt": <string>,
    "updatedAt": <string>,
    "supportsGeographicCoordinates": <Boolean>
}
  • No labels