# RESTful Application Development Guide

# Terminal Location

## Operations

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.

### Get Location

Gets the location of a single terminal

Note: | If a group URI is provided, an error response is returned.

#### Request

##### URI

`http://host:port/rest/terminal_location/location?query=${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>

}

}

Table 7-1 Enumeration values
Value | Meaning
--- | ---
`NoDelay` | The server should immediately return any location estimate that it currently has. If no estimate is available, the server return a failure indication. It may optionally initiate procedures to obtain a location estimate (e.g. to be available for a later request
`LowDelay` | The response time is more important than requested accuracy. The server attempts to fulfil any accuracy requirement, but not if it adds delay. A quick response with lower accuracy is more desirable than waiting for a more accurate response.
`DelayTolerant` | The network is expected to return a location with the requested accuracy even if this means not complying with the requested response time.

##### HTTP Method

GET

#### Response

##### ResponseContent-Type

application/json

##### Body

`{``"result"``: {`

`` `"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>

`}}`

#### Error Response

Service Exception

Policy Exception

### Get Location For Group

Gets the location for a group of terminals.

#### Request

##### URI

`http://host:port/rest/terminal_location/location?queryForGroup=${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>

}

}

##### HTTP Method

GET

#### Response

##### Response Content-Type

application/json

##### Body

`{``"result"``: [{`

`` `"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>

`}`

`}]}`

#### Error Response

Service Exception

Policy Exception

### Get Terminal Distance

Gets the distance between the terminal and a specified location

#### Request

##### URI

http://host:port/rest/terminal_location/distance?query=${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>

`}`

##### HTTP Method

GET

#### Response

##### Response Context-Type

application/json

##### Body

{`"result"`: "Integer"}<Distance in meters>

#### Error Response

Service Exception

Policy Exception

### Start Geographical Notifications

Starts a notification that is based on whether terminals enter or leave a specified geographic location

#### Request

##### URI

`http://host:port/rest/terminal_location/geographical-notification`

##### Request Content-Type

application/json

##### Body

`{`

`` `"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>

`}`

`}`

##### HTTP Method

PUT

#### Response

Note: | For the actual body of the notification as it is delivered to the designated endpoint, see Notifications.

##### Header

key= “Location” value = “host:port/rest/terminal_location/notifications”

The URI of the pub-sub server

#### Error Response

Service Exception

Policy Exception

### Start Periodic Notification

Starts a notification for a set of terminals at a defined interval

#### Request

##### URI

`http://host:port/rest/terminal_location/periodic-notification`

##### Request Content-Type

application/json

##### Body

`{`

`` `"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>

`}`

`}`

##### HTTP Method

PUT

#### Response

Note: | For the actual body of the notification as it is delivered to the designated endpoint, see Notifications.

##### Header

key= “Location” value = host:port/rest/terminal_location/notifications”

The URI of the pub-sub server

#### Error Response

Service Exception

Policy Exception

### End Notification

Stops both types of notification

#### Request

##### URI

`http://host:port/rest/terminal_location/notification/${correlator}`

${correlator}: The correlator passed in the reference attribute when the notification was established.

##### HTTP Method

DELETE

#### Response

##### Body

Empty

#### Error Response

Service Exception

Policy Exception

## Notifications

The content of notifications delivered to the designated endpoint.

### Location End

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.

### Location Error

The notification for a terminal or an entire notification is being ended because of an error.

`{"locationError": {`

`` `"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>

`}}`

### Location Notification

The notification

`{"locationNotification": {`

`` `"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>

`}}`

## Errors

The content of possible error messages.

### Service Exception

{`"error"`:{

`"type":`"org.csapi.schema.parlayx.common.v2_1.ServiceException"

`"message"`:"String"

}}

### Policy Exception

{`"error"`:{

`"type"`:"org.csapi.schema.parlayx.common.v2_1.PolicyException"

`"message"`:"String"

}}