|
|
The RESTful Terminal Location interfaces allow an application to get a location for an individual terminal or a group of terminals; to get the distance of the terminal from a specific location; and to start and stop notifications, based on geographic location or on a periodic interval.
In the listings below, bold indicates a required attribute, <> a descriptive comment.
| Note: | An HTML version of this information is at http://host:port/rest/terminal_location/index.html where host and port depend on the Oracle Communications Services Gatekeeper installation. |
Gets the location of a single terminal
| Note: | If a group URI is provided, an error response is returned. |
http://host:port/rest/terminal_location/location?query=${query}
"acceptableAccuracy": "Integer",<The range that the application considers useful. If the location cannot be determined within this range, the application would prefer not to receive the information.>
"address": "URI",<address of the terminal to be located>
"requestedAccuracy": "Integer",<The range over which the application wishes to receive location information. This may influence the choice of location technology to use (for instance, cell sector location may be suitable for requests specifying 1000 meters, but GPS technology may be required for requests below 100 meters).>
"tolerance": "NoDelay|LowDelay|DelayTolerant",<The priority of response time versus accuracy. See Table 7-1 for more information.>.
"maximumAge": {<The maximum acceptable age of the location information>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year", <The metric to use for time measurement>
"units": "Integer" <The number of units of the metric>
"responseTime": {<The maximum response time that the application can accept>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year", <The metric to use for time measurement>
"units": "Integer"<The number of units of the metric>
"accuracy": "Integer",<Accuracy of location in meters>
"latitude": "Float", <Location latitude>
"longitude": "Float",<Location longitude>
"timestamp": "Calendar",<Date and time the location was collected in ISO 8601 extended format >
"altitude": "Float" <Location altitude>
Gets the location for a group of terminals.
http://host:port/rest/terminal_location/location?queryForGroup=${queryForGroup}
"acceptableAccuracy": "Integer",<The range that the application considers useful. If the location cannot be determined within this range, the application would prefer not to receive the information.>
"addresses": ["URI"],<Addresses of the terminals to be located>
"requestedAccuracy": "Integer",<The range over which the application wishes to receive location information. This may influence the choice of location technology to use (for instance, cell sector location may be suitable for requests specifying 1000 meters, but GPS technology may be required for requests below 100 meters).>
"tolerance": "NoDelay|LowDelay|DelayTolerant",<The priority of response time versus accuracy. See Table 7-1 for more information.>.
"maximumAge": {<The maximum acceptable age of the location information>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year", <The metric to use for time measurement>
"units": "Integer" <The number of units of the metric>
"responseTime": {<The maximum response time that the application can accept>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year", <The metric to use for time measurement>
"units": "Integer"<The number of units of the metric>
"address": "URI", <Address of the specific terminal for which this item is relevant>
"reportStatus": "Retrieved|NotRetrieved|Error",<Retrieval status for this address. This allows for partial reports to avoid timeouts, etc.>
"currentLocation": {<Location of the terminal. Only provided if reportStatus = Retrived>
"accuracy": "Integer",<Accuracy of location in meters>
"latitude": "Float",<Location latitude>
"longitude": "Float",<Location longitude>
"timestamp": "Calendar",<Date and time the location was collected in ISO 8601 extended format >
"altitude": "Float"<Location altitude>
"errorInformation": {<If reportStatus=Error, this is the error. This provides error information for a single item out of a group.>
"messageId": "String",<Fault definition message identifier>
"text": "String",<Message text, with replacement variables>
"variables": ["String"]<Variables to substitute into text string>
Gets the distance between the terminal and a specified location
http://host:port/rest/terminal_location/distance?query=${query}
"address": "URI",<The address of the terminal>
"latitude": "Float",<The latitude of the specified location>
"longitude": "Float"<The longitude of the specified location>
{"result": "Integer"}<Distance in meters>
Starts a notification that is based on whether terminals enter or leave a specified geographic location
http://host:port/rest/terminal_location/geographical-notification
"addresses": ["URI"],<Addresses of the terminals to monitor>
"checkImmediate": "Boolean",< Whether the location of the terminals should be checked as soon as the notification is established>
"criteria": "Entering|Leaving",<Whether the notification should occur when the terminal is entering or leaving the specified location>
"frequency": {<Maximum frequency of notifications - can be seen as minimum time between notifications>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",<The metric to use for time measurement>
"units": "Integer"<The number of units of the metric>
"latitude": "Float",<The latitude of the center point of the location>
"longitude": "Float",<The longitude of the center point of the location>
"radius": "Float",<The radius of the circle around the center point, in meters>
"reference": {<Notification endpoint information>
"correlator": "String",<A correlator used to identify the notification>
"endpoint": "URI",<The endpoint address to which the notification should be delivered. This should be a channel name that begins: “/bayeux/${appInstanceId}”>
"interfaceName": "String"<A descriptive string to identify the type of notification>
"trackingAccuracy": "Float",<Acceptable error, in meters>
"count": "Integer",<The maximum number of notifications. For no maximum, leave this blank or specify zero>
"duration": {<The length of time over which notifications should occur. Do not specify to use the default time>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",<The metric to use for time measurement>
"units": "Integer"<The number of units of the metric>
| Note: | For the actual body of the notification as it is delivered to the designated endpoint, see Notifications. |
key= “Location” value = “host:port/rest/terminal_location/notifications”
Starts a notification for a set of terminals at a defined interval
http://host:port/rest/terminal_location/periodic-notification
"addresses": ["URI"],<Addresses of the terminals to monitor>
"frequency": {<Maximum frequency of notifications - can be seen as minimum time between notifications>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",<The metric to use for time measurement>
"units": "Integer"<The number of units of the metric>
"reference": {<Notification endpoint information>
"correlator": "String",<A correlator used to identify the notification>
"endpoint": "URI",<The endpoint address to which the notification should be delivered. This should be a channel name that begins: “/bayeux/${appInstanceId}”>
"interfaceName": "String"<A descriptive string to identify the type of notification>
"requestedAccuracy": "Integer",<Acceptable error, in meters>
"duration": {<The length of time over which notifications should occur. Do not specify to use the default time>
"metric": "Millisecond|Second|Minute|Hour|Day|Week|Month|Year",<The metric to use for time measurement>
"units": "Integer"<The number of units of the metric>
| Note: | For the actual body of the notification as it is delivered to the designated endpoint, see Notifications. |
key= “Location” value = host:port/rest/terminal_location/notifications”
Stops both types of notification
http://host:port/rest/terminal_location/notification/${correlator}
${correlator}: The correlator passed in the reference attribute when the notification was established.
The content of notifications delivered to the designated endpoint.
The notifications have ended for this correlator. Either count or duration has been completed. Not delivered in the case of an error or of the application ending the notification using End Notification.
{"locationEnd": {"correlator": "String"}}
The correlator that was passed in the initial set up of the notification.
The notification for a terminal or an entire notification is being ended because of an error.
"correlator": "String",<The correlator passed in when the notification was set up>
"reason": {<The description of the error>
"messageId": "String",<Fault definition message identifier>
"text": "String",<Message text, with replacement variables>
"variables": ["String"]<Variables to substitute into text string>
"address": "URI" <The address of the affected terminal>
"correlator": "String",<The correlator passed in when the notification was set up>
"data": [{<The location information for a terminal>
"address": "URI",<The address of the terminal>
"reportStatus": "Retrieved|NotRetrieved|Error",<Retrieval status for this address. This allows for partial reports to avoid timeouts, etc.>
"currentLocation": {<Location of the terminal. Only provided if reportStatus = Retrived>
"accuracy": "Integer",<Accuracy of location in meters>
"latitude": "Float",<Location latitude>
"longitude": "Float",<Location longitude>
"timestamp": "Calendar",<Date and time the location was collected in ISO 8601 extended format >
"altitude": "Float" <Location altitude>
"errorInformation": {<If reportStatus=Error, this is the error. This provides error information for a single item out of a group.>
"messageId": "String",<Fault definition message identifier>
"text": "String",<Message text, with replacement variables>
"variables": ["String"]<Variables to substitute into text string>
"criteria": "Entering|Leaving"<The criterion that triggered the notification. For geographical notifications only>
The content of possible error messages.
"type":"org.csapi.schema.parlayx.common.v2_1.ServiceException"
"type":"org.csapi.schema.parlayx.common.v2_1.PolicyException"
|