This chapter describes the Oracle Communications Services Gatekeeper OneAPI Terminal Location/MLP communication service in detail.
Applications use the RESTful OneAPI Terminal Location interface to get a location for an individual terminal or a group of terminals.
The Services Gatekeeper OneAPI Location interface complies with Open Mobile Alliance (OMA) specifications. See the discussion about OneAPI terminal location in Services Gatekeeper Statement of Compliance for a reference to the supported specification and RESTful bindings schema.
See ”Using the OneAPI RESTful Interfaces” in Services Gatekeeper Application Developer's Guide for general information on using the OneAPI RESTful interfaces.
The information provided in this document is based on the OneAPI specification and is provided here for convenience.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations are located here:
http://host:port/oneapi/1/terminallocation/application.wadl
Where host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
The Query Terminal Location operation retrieves the location of one or more terminals.
To retrieve the location of a specific terminal, provide its URI as the address value of the query object in the Request-URI of the GET method. Repeat the address parameter in the request for multiple terminals.
If the Query Terminal Location operation is successful, the response body contains a nested JSON data object containing the physical coordinates of each specific terminal and the date and time for when such data was last collected.
A locationRetrievalStatus is also provided for each terminal in the response body.
http://host:port/oneapi/1/terminallocation/queries/location?${query}
Where:
host and port are the host name and port of the machine on which the Services Gatekeeper Access Tier (AT) services are running.
${query} contains the following parameters:
address: String. The MSISDN of the mobile device to locate. Repeat the address parameter for multiple devices. The protocol and ’+' identifier must be used for MSISDN, and must be URL-escaped. %3A represents ’:' and %2B represents ’+'.
requestedAccuracy: Integer. The preferred accuracy of the result, in meters. Typically, when you request an accurate location, it will take longer to retrieve than a coarse location. For example, requestedAccuracy=10 will take longer than requestedAccuracy=100.
Standard header fields. If the request fails, the Status-Line header field contains the status code and the reason for the failure. For more information, see the discussion about "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
The location of the specific terminal is returned in the body of the response as the value of the terminalLocation JSON object. For more than one terminal, a terminalLocationList consisting of multiple terminalLocation objects are returned.
The parameters in this object are:
address: String. Denotes the terminal located (local and international numbers are supported).
currentLocation: JSON Object. Contains the following parameters:
accuracy: Integer
altitude: Integer
latitude: Number (floating point)
longitude: Number (floating point)
timestamp: String. The date and time when the terminal's geographical coordinates were collected, given in ISO 8601 extended format, yyyy-mm-ddThh-mm-ss.
locationRetrievalStatus: String. Contains one of the possible values:
Retrieved: Successful retrieval of the terminal location for the address
Not Retrieved: Services Gatekeeper was unable to locate the terminal location for the address
Error: A service policy or exception has occurred. For more information, see the discussion about "Errors and Exceptions" in Services Gatekeeper Application Developer's Guide.
The response body for this operation is represented by the following JSON data structure, where the value part of the name/value pair indicates its data type. A response containing multiple terminal locations are contained in a terminalLocationList structure, as in Example 22-4, "Query Multiple Mobile Terminals Location Response".
{"terminalLocation": {
"address": "String",
"currentLocation": {
"accuracy": "Integer",
"altitude": "Float",
"latitude": "Float",
"longitude": "Float",
"timestamp": "Calendar"
},
Example 22-1 shows a sample of a OneAPI Single Mobile Terminal Location request.
Example 22-1 Query Single Mobile Terminal Location Request
GET http://example.com/oneapi/1/terminallocation/queries/location?&address=tel&3A%2B15415550100&requestedAccuracy=1000 HTTP/1.1 Host: example.com:80 Accept: application/json
Example 22-2 shows a sample of a OneAPI Single Mobile Terminal response.
Example 22-2 Query Single Mobile Terminal Location Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"terminalLocationList": {"terminalLocation": {
"address": "tel:15415550100",
"currentLocation": {
"accuracy": "100",
"altitude": "1001.0",
"latitude": "-80.86302",
"longitude": "41.277306",
"timestamp": "2009-06-03T00:27:23.000Z"
},
"locationRetrievalStatus": "Retrieved"
}}}
Example 22-3 shows a sample of a OneAPI Multiple Mobile Terminals Location request.
Example 22-3 Query Multiple Mobile Terminals Location Request
GET http://example.com/oneapi/1/terminallocation/queries/location?&address=tel%3A%2B15415550100&address=tel%3A%2B15415550101&requestedAccuracy=1000 HTTP/1.1 Host: example.com:80 Accept: application/json
Example 22-4 shows a sample of a OneAPI Multiple Mobile Terminals Location request.
Example 22-4 Query Multiple Mobile Terminals Location Response
HTTP/1.1 200 OK
X-Powered-By: Servlet/2.5
Server: Example/v3
Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"terminalLocationList": {"terminalLocation": [
{ "address": "tel:15415550100",
"currentLocation": {
"accuracy": "100",
"altitude": "1001.0",
"latitude": "-80.86302",
"longitude": "41.277306",
"timestamp": "2009-06-03T00:27:23.000Z"},
"locationRetrievalStatus": "Retrieved"},
{ "address": "tel:15415550101",
"errorInformation": {
"messageId": "SVC0001",
"text": "A service error occurred. %1 %2",
"variables": ["Location information is not available for", "tel:15415550101"]
},
"locationRetrievalStatus": "Error"
}
]}}