5 OneAPI Terminal Location

This chapter describes the operations in the OneAPI Terminal Location interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.

About the Terminal Location Interface

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. For more information on OMA, see:

http://www.openmobilealliance.org/Technical/release_program/docs/CopyrightClick.aspx?pck=ParlayREST&file=V2_0-20110111-C/OMA-TS-ParlayREST_OneAPIProfile-V2_0-20110111-C.pdf

The information provided in this document is based on the OneAPI specification and is provided here for convenience.

REST Service Descriptions Available at Run-time

When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at

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.

Query Mobile Terminal Location

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.

Authorization

Basic or OAuth 2.0

HTTP Method

GET

URI

http://host:port/oneapi/1/terminallocation/1.0/location/queries/location?query${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.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions" for more information.

Response Body

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. See "Errors and Exceptions" for more information.

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 5-4, "Query Multiple Mobile Terminals Location Response".

{"terminalLocation": {
    "address": "String",
    "currentLocation": {
        "accuracy": "Integer",
        "altitude": "Float",
        "latitude": "Float",
        "longitude": "Float",
        "timestamp": "Calendar"
    },

Examples

Example 5-1 shows a sample of a OneAPI Single Mobile Terminal Location request.

Example 5-1 Query Single Mobile Terminal Location Request

GET http://example.com/oneapi/1/location/queries/location?&address=tel&3A%2B15415550100&requestedAccuracy=1000 HTTP/1.1
Host: example.com:80
Accept: application/json

Example 5-2 shows a sample of a OneAPI Single Mobile Terminal response.

Example 5-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 5-3 shows a sample of a OneAPI Multiple Mobile Terminals Location request.

Example 5-3 Query Multiple Mobile Terminals Location Request

GET http://example.com/oneapi/1/location/queries/location?address=tel%3A%2B15415550100&address=tel%3A%2B15415550101&requestedAccuracy=1000 HTTP/1.1
Host: example.com:80
Accept: application/json

Example 5-4 shows a sample of a OneAPI Multiple Mobile Terminals Location request.

Example 5-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"
    }
]}}