Base Locations 

The virtual users are located in multiple cities in the United States and move in predictable patterns. Each of the following cities has a group of seventeen virtual users: 

Travel Patterns

Virtual users move in East-West or North-South direction, following a predictable pattern. Starting on the hour, all users in a given city start at the latitude and longitude listed in Table 1 . They travel at a constant speed in their assigned initial direction. After thirty minutes, users reverse direction and return to the common geographic point.

The rate of travel is determined by the maximum distance that each mobile moves in the first thirty-minutes, as shown in the table below. Note that one user in each city, 555-0000, is stationary; this supports the testing of additional use cases.

 Virtual Users by Number

Accuracy Emulation 

If the device is shown as "GPS-enabled" in Table 2, the API returns a location with GPS accuracy if "acceptableAccuracy" is less than 14000 meters. Devices that are not "GPS-enabled" will only return cell-sector accuracy. The actual values of the accuracy vary, but generally, GPS accuracy is a few hundred meters and cell-sector accuracy is 12000 to 14000 meters. 

(For more information on using accuracy and delay parameters in live applications, see Accuracy and Delay Parameters.) 

Understanding RESTful Operations: Requests and Responses. 

To use location-based services in a live app, it is necessary to blend two RESTful services: a subscriber service and a location service. Your location messaging app is deployed on one (or more) of the URLs that you specified when registering for an application key.

Implement your app with your choice of programming languages and tools. Your application makes https GET requests to the OAS platform URL specified for subscriber and location operations, filling parameter values as appropriate. (A few request parameters are optional; most are required. Parameter order is not required.) Your app should expect XML responses in the same TCP session for the request. The application inspects the XML response parameters to determine its subsequent behavior.

Note on datatypes int and long: 

• "int" : A parameter datatype with a range of -2^31 to 2^31 -1
• "long" : A parameter datatype with a range of  -2^63 to 2^63 -1

Note: both http and https are supported.

Description 

Locates a single user. 

URL

http://api.openapiservice.com/v1.0/location/getLocation

Sample Request 

https://api.openapiservice.com/v1.0/location/getLocation? appkey=a44f2nz9ql30cpou7wev8te3&phoneNumber=19175550001
&requestedAccuracy=100&acceptableAccuracy=1000&maximumAge=300000&responseTime=60000&tolerance=DELAY_TOLERANT

Request Message Parameters  

Example of Success Response

<ns:getLocationResponse xmlns:ns="http://service.las.alu.com/xsd">
  <ns:return>SU100</ns:return>
<ns:reason>Success</ns:reason>
<ns:phoneNumber>19175550001</ns:phoneNumber>
  <ns:location>
    <ns:latitude>41.0355</ns:latitude>
    <ns:longitude>-82.2419</ns:longitude>
    <ns:altitude>0.0</ns:altitude>
    <ns:accuracy>150</ns:accuracy>
    <ns:timestamp>1242399982540</ns:timestamp>
  </ns:location>
</ns:getLocationResponse>

Example of Failure Response

<ns:getLocationResponse xmlns:ns="http://service.las.alu.com/xsd">
  <ns:return>RE405</ns:return>
  <ns:reason>Subscriber 19175550001 not found</ns:reason>
  <ns:phoneNumber>19175550001</ns:phoneNumber>
</ns:getLocationResponse>

Response Message Parameters 

The response message contains XML content with the following parameters: 

Location data parameters: