Network-initiated

Location API
V 1.0

Development and access guide

Free distribution

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 2/15

Índice
Introduction 3
Location-Based Services Overview 4
Location API Overview 6
Using MLP 3.0.0 8
Steps to Creating a Location-Enabled Service 12

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 3/15

I. Introduction
NII Network-based Location API (hereto forth known as the Location API) allows NII’s business
partners and corporate customers to develop a wide array of applications to be enhanced with
location data.The Location API does this through the use of standard web services known as the
MLP (Mobile Location Protocol), a location standard supported by the OMA (Open Mobility
Alliance).

Currently, the access to the Location API is granted for companies which have signed partnership
agreements with NII, as well as large NII enterprise customers who are developing an application
for in-house use.

This document provides information on the NII’s implementation of the MLP. It also defines how you
can gain access to the systems you should use for initial development, integration and pre-
production testing and launch.

This guide assumes that you have at least a basic understanding of data networking concepts,
software development, the eXtensible Mark-up Language (XML), and how to transmit, receive and
parse an XML document.

1) OMA MLP

The Open Mobile Alliance (OMA) Mobile Location Protocol (MLP) interface is an XML interface
that enables communication between location-based services and location infrastructure.The
interface was developed by the Location Interoperability Forum (LIF) – an international consortium
that promotes open standards and interoperability for mobile location services.Since OMA (at the
time under the responsibility of LIF) first created MLP, it has released updated versions.NII
Location API supports version 3.0.0.

The first full public release of the OMA MLP protocol is MLP 3.0.0.The interface definition for this
v e r s i o n i s a v a i l a b l e a t t h e O p e n M o b i l e A l l i a n c e We b s i t e a t : h t t p : / /
www.openmobilealliance.org/tech/LIF/index.htm.

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 4/15

II. Location-Based Services Overview

By definition, mobile location services use the location of mobile subscriber (or mobile station) to
enable or enhance the subscriber experience within client applications. Location-based services
have been around for decades – for example: fleet tracking services facilitated by mobile data
networks and GPS terminals – but the penetration of these services into the consumer market has
been very limited.The emergence of cellular network-based location determination systems has
propelled mobile location services into the mainstream, by making it easy and convenient to
position standard mobile telephones.

Increasing numbers of mobile operators are implementing the capability to locate mobile phones
in their wireless networks.Several different methods to accomplish the determination of the
location of a phone exist.The most common and well-known positioning methods are briefly
described in the next section, Positioning Methods.

Different methods have been developed to enable mobile operators to estimate the horizontal
position of mobile subscribers.This section describes two methods supported by NII’s Location
API:cell-based positioning and GPS positioning.

1) CELL-SITE TRIANGULATION-BASED POSITIONING

Cell-site triangulation-based positioning provides a location coordinate based on the strength of

the signal that is received from the cell site that is serving the subscriber, as well as the signal
strength of the signal that is received from the other cell sites that are near the mobile
subscriber.The location infrastructure contains information on the location coordinate of each cell
sector.Combining this information with custom wave propagation models allows the network to
estimate the location of the subscriber using triangulation.By continuously monitoring and tuning
the wave propagation models that are used, the estimated accuracy can be adjusted based on
changes to the environment that would affect the cellular strength.

In the diagram in Figure 1 below, a mobile subscriber is being served by cell site A, with cell site B
and C as neighboring cell sites.The strength of the signals from all three cell sites is measured by
the mobile station and sent to the network for triangulation and the subscriber’s appropriate
location is calculated with estimated accuracy.

Typical accuracy values measured for cell-based positioning can range from 100 meters to 2,000
meters depending on the density of cell site, and the ranges vary by market to market.Developers
shall consult each NII market for further information regarding the ranges.

2) GPS-BASED POSITIONING

GPS-based positioning provides a significant improvement in horizontal accuracy over cell-based

positioning.In traditional GPS positioning, the mobile device receives all data required from the
GPS satellite and calculates its position.NII uses Assisted GPS (AGPS).In an assisted GPS system,
GPS information from the constellation of GPS satellites is augmented with additional location
information from AGPS servers.Assist servers can access information from the location network and
have more computing power than the traditional GPS-enabled devices.With assistance from the
network, handsets can operate more quickly and efficiently than they would unassisted, because
handsets share tasks they would normally handle with the assist server.Nextel handsets are
capable of requesting assist data from the Nextel AGPS servers.The AGPS servers are connected

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 5/15

to a number of reference GPS receivers spread throughout the world.The AGPS servers contain
information on the GPS satellites that can be used to obtain each handset’s location.The AGPS
servers also contain information on how to get the first location fix for the handset more
quickly.Therefore, the AGPS enables you to reduce the time-to-first-fix (TTFF) whereas non-
assisted cold start positioning may take a few minutes.Figure 2 depicts the AGPS positioning
method.

Typical precision values measure for GPS positioning methods can range from 5 meters to 50
meters depending on a variety of conditions, including atmospheric conditions and number of
satellites visible to the handset.

With GPS-based positioning, there are different types of position requests, or fixes, that can be
executed:

Standard Fix

Standard fixes include the phone’s position expressed in latitude and longitude as well as a
degree of horizontal uncertainty. Most applications only require minimal location information, as
returned in standard fixes. Since standard fixes contain minimal location information, they are
returned faster than extended fixes. For examples of standard fixes, see examples on page 15.

Extended Fix

In addition to the position and position uncertainty information in standard fixes, extended fixes
include direction, speed, altitude, and altitude uncertainty. To
trigger an extended fix, you must include a value for altitude
uncertainty in the location request. If you only require speed
or heading information, make sure to put in a large
uncertainty for altitude. If the system cannot meet your quality
of position requirements, you may receive an error message in
return. For an example of an extended fix request, see
Extended Fix on page 16.

Figure 1: Cell-based Positioning

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 6/15

III. Location API Overview

Figure 3 below depicts a high level overview of the call flow
for NII’s Location API framework.The Location API highlighted
between the LSC Client (location-enabled 3rd party
application) and AGPS server uses the MLP protocol as
described previously.Each session consists of a request and a
response.Each request must carry the proper authentication
information and must pass the authorization checks before
location is returned.

LCS Client:A software and/or hardware entity that interacts

(via server to server) with AGPS server for the purpose of
obtaining location information for one or more mobile
stations. Figure 2: AGPS Positioning

Location API: Location API is a gateway into NII’s network to

securely and easily obtain subscriber location data.Location API is represented by Openwave
location server called Location Studio.

1) AUTHENTICATION AND AUTHORIZATION

Location API has authentication and security controls to ensure that only authorized LCS Clients (or
3rd party application developer) can request the location of subscribers. Location API
authenticates the client ID and password that is included in each location request. After clients are
authenticated, Location API authorizes location requests by clients based on the settings in the
client profiles.

Authentication and Security

All transactions against Location API require positive authentication of the client’s credentials
(client ID and password). The client ID and password must be embedded with each request.
Because of the information in each MLP location request (such as IDs and passwords), it is
standard practice to use SSL or a Virtual Private Network (VPNs) for security.

Authorization

NII maintains a profile for each client that controls client authorization to make location requests,
including restricting the accuracy of location data that can be requested by the application. It is
possible that location requests may be denied, or altered in the case of accuracy limitations,
based on the settings in the client profile.

2) SUBSCRIBER PRIVACY

NII is dedicated to protecting the privacy of its customers.To this end NII will only allow querying
of devices for which permission has been granted by the device owner.Therefore, the access to
subscriber location via the network-based Location API regime assumes that the corporate-level
privacy policy has been established between NII and customer.The corporate-level privacy policy
applies to the corporate-liable phones, and it assumes that the company representative (or the
account owner) is authorized to grant the privacy permission on behalf of the phones in the

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 7/15

account.It is important that the phones that are authorized to be tracked by the client have been
granted permission by the account owner.

GPS Assist
Server Location
API
(request/
response) Internet

Nextel LCS Client

Wireless (3rd party
Network application)

Triangulation
Server

Figure 3: Location API Overview

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 8/15

IV. Using MLP 3.0.0

This section describes how to use the MLP 3.0.0 interface with Location Studio 2.1.Information is
provided for both location requests and location responses.For a complete reference the text in
this document should be combined with the OMA MLP 3.0.0 specification, which can be
downloaded from the OMA website at http://www.openmobilealliance.org/tech/LIF/index.htm.

3) THE LOCATION REQUEST

The section describes the location requests made by client applications using the MLP 3.0.0.

Header information

Each MLP request contains a header element (hdr) that contains client credentials. The client
credentials are contained in the client element. The client contains two subfields: id and pwd. The
following illustrates a header.

<hdr ver='3.0.0'>
<client>
<id>testlst</id>
<pwd>password</pwd>
</client>
</hdr>

Mobile Identification

The MLP interface supports the use of either North American Mobile Identification Number (MIN)
or GSM Mobile Subscriber ISDN (MSISDN) or Private Telephone Number (PTN) as the Mobile
Subscriber Identifier (MSID).A subscriber’s MIN, MSISDN, or PTN is simply his or her mobile
telephone number. By default the expected MSID is an MSISDN or PTN.In order to specify the
MSID as a MIN, MIN must be listed as the MSID type using the msid_type element as shown in the
following example with two mobile numbers:

<msids>
<msid msid_type=”MIN”>123456788</msid>
<msid msid_type=”MIN”>123456789</msid>
</msids>

Location requests that contain multiple MSIDs require that the location for all the subscribers be
found before the location response is returned.So if you request the location for two subscribers
(as shown in the preceding example), then both of the subscriber locations must be found before
the locations of the subscribers are returned.

Controlling Age of Location and Response Time

There are two parameters that control the accepted age of location and Response time in MLP:

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 9/15

loc_type: Defines the maximum age of the location to be accepted by the client. There are three
types of location requests defined in MLP 3.0.0: CURRENT, LAST, and CURRENT_OR_LAST. The
default setting, if not specified, is CURRENT (which ignores the location cache). The format in the
MLP request is <loc_type type="CURRENT_OR_LAST" />.

resp_timer: Defines how many seconds the application is willing to wait for a response before a
response is returned. If resp_timer is included in the request it overrides the value provided in
resp_req.

Controlling Location Format

In MLP 1.2 it was possible to specify the coordinate format in the GEO_INFO element, but in MLP
3.0.0 this is no longer the case.The geo-info element only specifies the coordinate reference
system, as defined by EPSG.Location API supports the MLP default coordinate reference system,
WGS-84, which corresponds to EPSG 4326, version 6.1.Thus, the GEO_INFO element is ignored
and should not be included requests.

Note that the flexibility in he returned text-encoding of the coordinates that was possible in MLP
1.2 is not possible.The format is now DDD MM SS.sssH, where DDD is degrees, MM is minutes, and
SS:sss is seconds with three decimals and H is the heading, (that is, N, S, W or E).For example,

<X>45 07 24.123N</X>
<Y>100 06 22.111E</Y>
<Z>5280</>

Observe that X corresponds to the latitude (northing) and Y to the longitude (easting).

Standard vs Extended Fix Requests

The NII implementation supports both standard and extended fix requests.A standard fix request
will include the latitude, longitude, and horizontal accuracy parameters.An extended fix request
will include the latitude, longitude, and horizontal accuracy parameters, as well as altitude
accuracy, velocity, and direction parameters.Unless specifically requested, a standard fix will be
returned by Location API.To request an extended fix location, set the alt_acc parameter to a non-
zero value, such as 1000.

To request a location with an extended fix:

<eqop>
<resp_timer>0015</resp_timer>
<alt_acc>1000</alt_acc>
</eqop>

4) THE LOCATION RESPONSE

This section describes the location response sent from the system back to the client application
using MLP 3.0.0 in response to a location request.

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 10/15

Location Accuracy

The following elements of the response illustrate the returned location information and the radius
of uncertainty (<radius> tag), which is 1000 meters in this case. The radius is always defined in
meters.

There are many shapes defined in MLP, but Location Studio 2.1 always uses the CircularArea
element.

<shape>
! <CircularArea>
! ! <coord>
<X>45 07 24.123N</X>
! ! ! <Y>100 06 22.111E</Y>
! ! ! <Z>5280</Z>
! ! </coord>
! ! <radius>1000</radius>
! </CircularArea>
</shape>

Location Response Time

Nextel’s location service cannot provide a guaranteed response time for sending location
information back to the client application. The locating procedure involves querying Nextel’s
location assistance servers, which in turn may need to page the mobile device for its current
location. This procedure can take variable amounts of time to complete, depending on the various
network and geographical conditions.The application developer should be aware that a
positioning operation can take as long as 60 seconds to complete.Times increase in busy periods.

Since response times vary and could be delayed by network conditions, NII location servers
maintain a cache of old subscriber locations. This cache can be made use of by specifying a
particular Quality of Position (QoP) parameter in the MLP request, which will allow for slightly
older information to be returned in exchange for a faster response.Please refer to Openwave,
“MLP 3.0.0 for Location Studio Interface Control Document” Version 0.5, 2003 for more
information.

Table 1: loc_type Parameters

LOC_TYPE Value Behavior
LAST Requesting the last known location of the subscriber. With this value, the
LBS system can only supply a cache location (if available). If the cache
location is not available, then the system responds to the application
with error 6.

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 11/15

CURRENT_OR_LAST Requesting the current location of the subscriber.If the cached location
for the subscriber is less than 10 minutes old, the cached location will be
returned.If the cached location is not available, the system responds
with no location data along with error 6.

For the NII implementation, this value provides the same result as
CURRENT.
CURRENT Requesting the current location of the subscriber.If the cached location
for the subscriber is less than 10 minutes old, the cached location will be
returned.If the cached location value is not available, the system
responds with no location data along with error 6.

For the NII implementation, this value provides the same result as
CURRENT_OR_LAST.

A component of the response is the time that the location was obtained. The <time> parameter is
in the format <time>YYYYMMDDHHMMSSss</time>. The <time> value can be used to
determine if the location is current or to determine the age of location returned from cache. In the
following example the time reported is April 1, 2002 at 11:46 AM, and the time reference is UTC
offset with one hour.

Time is reported using Universal Metric Time (UMT) and not Greenwich Mean Time (GMT).
Returned times are offset in UMT from the location of the Location Studio server and not
necessarily your location.

<pd>
<time utc_off="+0100">20030401114600</time>

5) GENERAL PROGRAMMING GUIDELINES

This following are guidelines and information that will help you improve performance and reduce
problems.
• Set resp_timer to 60 seconds.This will reduce the chance of retransmitting requests and
getting cached location
• MUST set a value for hor_acc.This will allow the system sufficient time to return best possible
position
• Set hor_acc to be at 1000 meters or less.This will allow the system sufficient time to return
best possible position.

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 12/15

V. Steps to Creating a Location-Enabled Service

This section describes the steps you should follow to create a location enabled client application.

1) CONNECTING TO THE OPENWAVE TEST SERVER

The Openwave Location Studio Test server provides two methods for testing and verifying your
location application. The first is a test harness, where you can cut and paste the XML request
document in a standard browser window and then view the XML response. The test harness is
provided to assist you with debugging and allow you to test various location request scenarios.
The second method of testing involves posting the XML request documents directly from your
application (using Java, C++ or any other development language) to the actual LSt MLP 3.0.0
interface.

The Openwave Location Studio test server is available to all members of the Openwave
Developer Program. This test server, and the data contained within this server is provided for your
own personal use to test and demonstrate applications using the Openwave Location Manager
and Location Studio products. The data contained in the test server is simulated and is not linked
to any person or business.

The test server is constantly maintained on a best efforts basis, but its availability is not
guaranteed. If this site is not available for any reason, please send a message to
developer@openwave.com to report the problem.

Browser Test Harness

Direct your browser to the following URL:

http://72.165.137.101:14000/lst_test/client/index.htm

and then click the MLP300 Servlet link.

By default, the page contains a form with the following empty XML request document:

<?xml version = "1.0" ?>

<!DOCTYPE svc_init SYSTEM "MLP_SVC_INIT_300.DTD" [
<!ENTITY % extension SYSTEM
"OPWV_MLP_extension_request.dtd">
%extension;
]>
<svc_init ver="3.0.0">
<hdr ver="3.0.0">
<client>
<id>theasp</id>
<pwd>thepwd</pwd>
</client>
</hdr>
<slir ver="3.0.0">
<msids>
<msid type="MIN">3033813000</msid>

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 13/15

</msids>
<loc_type type="LAST" />
<opwv_extension_request>Zone</opwv_extension_request>
</slir>
</svc_init>

Cut and paste from the Examples section of this document to insert XML requests covering a
variety of common request scenarios.

The test server does not support CURRENT. When sending requests to the test server, you must
specify a loc_type other than CURRENT, such as “CURRENT_OR_LAST.” All live network
implementations support CURRENT requests.

HTTP Post URL

The browser test harness described previously simply takes the XML and posts it to the actual MLP
3.0.0 request interface of LSt. After you have verified your XML request is valid and you know
what response to expect, you can test your application by posting to the following URL:

http://72.165.137.101:14000/locationstudio/mlp300

2) TEST SERVER CONFIGURATION

This section describes how you should use the Openwave Location Service Test Server in order to
test MLP with your client application.

Username/Password

The following user ID and password are provided for use by all Openwave Developer Program
members to test the Location Studio 2.1 MLP 3.0.0 interface:

<id> infoservdemo1
<pwd> infoservdemo1

In the XML request document these credentials are formatted as follows:

<client>
! <id>infoservdemo1</id>
! <pwd>infoservdemo1</pwd>
</client>

Test Data

The following is the current test data available in the Location Studio Test Server.

! <msids>
! ! <msid>3035551001</msid>

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 14/15

! </msids>

• A variety of MINs are included to provide for the following:

• Different location data (all within Boulder, Colorado USA)
• A variety of scenarios to simulate
• Different location accuracy (typical of AGPS and cell-sector technologies)
• Different subscriber privacy settings

Table 2 describes the details of the test scenarios and data.

Table 2: Test server data

MIN Condition Returned Location Data
Y X A c c u r a c y L o c a t i o n <poserr>
(DDD MM (DDD MM radius Age Code
SS.sssH) SS.sssH)
303-555-1000 S u b s c r i b e r N o t - - - - 6
Provisioned
303-555-1001 T y p i c a l H i g h - 1 0 5 1 6 40 01 16.355N 20 < 10 min 0
Accuracy (AGPS) 02.675W
303-555-1002 Typical Cell-Sector 1 0 5 0 2 39 46 07.564N 300 < 10min 0
(Urban) 36.445W
303-555-1003 Typical Cell-Sector 1 0 5 0 2 39 51 14.399N 1,000 < 10 min 0
(Suburban) 53.858W
303-555-1004 Typical Cell-Sector 1 0 5 1 6 40 00 59.558N 10,000 < 10 min 0
(Rural) 07.154W
303-555-1005 Standard location 1 0 5 1 2 39 45 15.778N 1000 < 10 min 0
34.322W
303-555-1006 Standard location 1 0 5 0 4 40 00 00.000N 1000 < 10 min 0
31.389W
303-555-1007 Standard location 1 0 4 5 6 40 21 12.726N 1000 < 10 min 0
21.811W
303-555-1008 Standard location 1 0 4 4 0 40 31 30.910N 1000 < 10 min 0
36.353W
303-555-1009 Standard location 1 0 5 0 7 40 07 24.437N 1000 < 60 min 0
24.452W
303-555-1010 M a s t e r P r i v a c y 1 0 5 0 7 40 07 24.437N 1000 < 10 min 203
Enabled 24.452W
303-555-1011 Monday – Friday 1 0 5 0 7 40 07 24.437N 1000 < 10 min 0, or
only 24.452W 203
303-555-1012 S a t u r d a y a n d 1 0 5 0 7 40 07 24.437N 1000 < 10 min 0, or
Sunday only 24.452W 203
303-555-1013 Standard location 1 0 5 0 7 40 07 24.437N 1000 > 60 min 0, or
24.452W 201
303-555-1014 Client Relationship 1 0 5 0 7 40 07 24.437N 1000 < 10 min 0, or
Disabled 24.452W 203
303-555-1015 Client Relationship 1 0 5 0 7 40 07 24.437N 1000 < 10 min 0, or
Not Available 24.452W 203

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08

 15/15

3) HOW DO I GET SUPPORT?

NII Developer Program provides support for integration with NII’s Location API. You may direct
questions to developerprogram@nii.com, or visit

http://programa.nii.com.

The Openwave Developer Program provides support for the Openwave test server described
above.Support personnel are located in two time zones: North America Pacific Time (GMT – 8)
and UK Time (GMT + 0).

You may direct questions to the developer support team as follows:

Email: developer@openwave.com

Online forum: http://devforum.openwave.com

Or you may download and review support material from the developer website at

http://developer.openwave.com/dvl/tools_and_sdk/location_studio/index.htm

©2008 NII Holdings, Inc.! v 1.0.0 11/19/08