Nii Lbs-lifmlp Development Guide

8/9/2019 Nii Lbs-lifmlp Development Guide

1/15

Network-initiated

Location API

V 1.0

Development and access guideFree 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

2/15



3/15

I. Introduction

NII Network-based Location API (hereto forth known as the Location API) allows NIIs businesspartners and corporate customers to develop a wide array of applications to be enhanced withlocation 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 MobilityAlliance).

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

This document provides information on the NIIs implementation of the MLP. It also defines how youcan 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 andparse an XML document.

1) OMA MLP

The Open Mobile Alliance (OMA) Mobile Location Protocol (MLP) interface is an XML interfacethat enables communication between location-based services and location infrastructure.Theinterface was developed by the Location Interoperability Forum (LIF) an international consortiumthat promotes open standards and interoperability for mobile location services.Since OMA (at thetime under the responsibility of LIF) first created MLP, it has released updated versions.NIILocation 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 thisvers ion i s avai lable at the Open Mobi le Al l iance Webs i te at : h t t p : / /www.openmobilealliance.org/tech/LIF/index.htm .

3/15

http://www.openmobilealliance.org/tech/LIF/index.htmhttp://www.openmobilealliance.org/tech/LIF/index.htmhttp://www.openmobilealliance.org/tech/LIF/index.htmhttp://www.openmobilealliance.org/tech/LIF/index.htmhttp://www.openmobilealliance.org/tech/LIF/index.htmhttp://www.openmobilealliance.org/tech/LIF/index.htm


4/15

II. Location-Based Services Overview

By definition, mobile location services use the location of mobile subscriber (or mobile station) toenable or enhance the subscriber experience within client applications. Location-based serviceshave 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 hasbeen very limited.The emergence of cellular network-based location determination systems haspropelled mobile location services into the mainstream, by making it easy and convenient toposition standard mobile telephones.

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

Different methods have been developed to enable mobile operators to estimate the horizontalposition of mobile subscribers.This section describes two methods supported by NIIs 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 ofthe signal that is received from the cell site that is serving the subscriber, as well as the signalstrength of the signal that is received from the other cell sites that are near the mobilesubscriber.The location infrastructure contains information on the location coordinate of each cellsector.Combining this information with custom wave propagation models allows the network toestimate the location of the subscriber using triangulation.By continuously monitoring and tuningthe wave propagation models that are used, the estimated accuracy can be adjusted based onchanges 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 Band C as neighboring cell sites.The strength of the signals from all three cell sites is measured bythe mobile station and sent to the network for triangulation and the subscribers appropriatelocation is calculated with estimated accuracy.

Typical accuracy values measured for cell-based positioning can range from 100 meters to 2,000meters depending on the density of cell site, and the ranges vary by market to market.Developersshall 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-basedpositioning.In traditional GPS positioning, the mobile device receives all data required from theGPS 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 locationinformation from AGPS servers.Assist servers can access information from the location network andhave more computing power than the traditional GPS-enabled devices.With assistance from thenetwork, handsets can operate more quickly and efficiently than they would unassisted, becausehandsets share tasks they would normally handle with the assist server.Nextel handsets arecapable of requesting assist data from the Nextel AGPS servers.The AGPS servers are connected

4/15



5/15

to a number of reference GPS receivers spread throughout the world.The AGPS servers containinformation on the GPS satellites that can be used to obtain each handsets location.The AGPSservers also contain information on how to get the first location fix for the handset morequickly.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 positioningmethod.

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

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

Standard Fix

Standard fixes include the phones position expressed in latitude and longitude as well as adegree of horizontal uncertainty. Most applications only require minimal location information, as

returned in standard fixes. Since standard fixes contain minimal location information, they arereturned 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 fixesinclude direction, speed, altitude, and altitude uncertainty. Totrigger an extended fix, you must include a value for altitudeuncertainty in the location request. If you only require speedor heading information, make sure to put in a largeuncertainty for altitude. If the system cannot meet your qualityof position requirements, you may receive an error message inreturn. For an example of an extended fix request, seeExtended Fix on page 16.

5/15


Figure 1: Cell-based Positioning


6/15

III. Location API Overview

Figure 3 below depicts a high level overview of the call flowfor NIIs Location API framework.The Location API highlightedbetween the LSC Client (location-enabled 3rd party

application) and AGPS server uses the MLP protocol asdescribed previously.Each session consists of a request and aresponse.Each request must carry the proper authenticationinformation and must pass the authorization checks beforelocation is returned.

LCS Client:A software and/or hardware entity that interacts(via server to server) with AGPS server for the purpose ofobtaining location information for one or more mobilestations.

Location API: Location API is a gateway into NIIs network to

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

1) AUTHENTICATION AND AUTHORIZATION

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

Authentication and Security

All transactions against Location API require positive authentication of the clients 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 isstandard 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 ispossible 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 queryingof devices for which permission has been granted by the device owner.Therefore, the access tosubscriber location via the network-based Location API regime assumes that the corporate-levelprivacy policy has been established between NII and customer.The corporate-level privacy policyapplies to the corporate-liable phones, and it assumes that the company representative (or theaccount owner) is authorized to grant the privacy permission on behalf of the phones in the

6/15


Figure 2: AGPS Positioning


7/15

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

7/15


Internet

LCS Client(3rd partyapplication)

TriangulationServer

Figure 3: Location API Overview

NextelWireless

Network

LocationAPI(request/response)

GPS AssistServer


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 isprovided for both location requests and location responses.For a complete reference the text inthis 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 clientcredentials are contained in the client element. The client contains two subfields: id and pwd. Thefollowing illustrates a header.

testlst

password

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 MobileSubscriber Identifier (MSID).A subscribers MIN, MSISDN, or PTN is simply his or her mobiletelephone number. By default the expected MSID is an MSISDN or PTN.In order to specify theMSID as a MIN, MIN must be listed as the MSID type using the msid_type element as shown in thefollowing example with two mobile numbers:

123456788

123456789

Location requests that contain multiple MSIDs require that the location for all the subscribers befound 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 beforethe 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:

8/15

http://www.openmobilealliance.org/tech/LIF/index.htmhttp://www.openmobilealliance.org/tech/LIF/index.htm


9/15

loc_type: Defines the maximum age of the location to be accepted by the client. There are threetypes of location requests defined in MLP 3.0.0: CURRENT, LAST, and CURRENT_OR_LAST. Thedefault setting, if not specified, is CURRENT (which ignores the location cache). The format in theMLP request is .

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

Controlling Location Format

In MLP 1.2 it was possible to specify the coordinate format in the GEO_INFO element, but in MLP3.0.0 this is no longer the case.The geo-info element only specifies the coordinate referencesystem, 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 ignoredand should not be included requests.

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

45 07 24.123N

100 06 22.111E

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 requestwill include the latitude, longitude, and horizontal accuracy parameters.An extended fix requestwill include the latitude, longitude, and horizontal accuracy parameters, as well as altitudeaccuracy, velocity, and direction parameters.Unless specifically requested, a standard fix will bereturned 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:

00151000

4) THE LOCATION RESPONSE

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

9/15



10/15

Location Accuracy

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

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

! ! ! 45 07 24.123N! ! ! 100 06 22.111E! ! ! 5280! ! ! ! 1000!

Location Response Time

Nextels location service cannot provide a guaranteed response time for sending locationinformation back to the client application. The locating procedure involves querying Nextelslocation assistance servers, which in turn may need to page the mobile device for its currentlocation. This procedure can take variable amounts of time to complete, depending on the variousnetwork and geographical conditions.The application developer should be aware that apositioning 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 serversmaintain a cache of old subscriber locations. This cache can be made use of by specifying aparticular Quality of Position (QoP) parameter in the MLP request, which will allow for slightlyolder 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 moreinformation.

Table 1: loc_type Parameters

LOC_TYPE Value Behavior

LAST Requesting the last known location of the subscriber. With this value, theLBS system can only supply a cache location (if available). If the cachelocation is not available, then the system responds to the applicationwith error 6.

10/15



11/15

CURRENT_OR_LAST Requesting the current location of the subscriber.If the cached locationfor the subscriber is less than 10 minutes old, the cached location will bereturned.If the cached location is not available, the system respondswith no location data along with error 6.

For the NII implementation, this value provides the same result asCURRENT.

CURRENT Requesting the current location of the subscriber.If the cached locationfor the subscriber is less than 10 minutes old, the cached location will bereturned.If the cached location value is not available, the systemresponds with no location data along with error 6.

For the NII implementation, this value provides the same result asCURRENT_OR_LAST.

A component of the response is the time that the location was obtained. The parameter is

in the format YYYYMMDDHHMMSSss. The value can be used todetermine if the location is current or to determine the age of location returned from cache. In thefollowing example the time reported is April 1, 2002 at 11:46 AM, and the time reference is UTCoffset 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 notnecessarily your location.

20030401114600

5) GENERAL PROGRAMMING GUIDELINES

This following are guidelines and information that will help you improve performance and reduceproblems.

Set resp_timer to 60 seconds.This will reduce the chance of retransmitting requests andgetting cached location

MUST set a value for hor_acc.This will allow the system sufficient time to return best possibleposition

Set hor_acc to be at 1000 meters or less.This will allow the system sufficient time to returnbest possible position.

11/15



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 yourlocation application. The first is a test harness, where you can cut and paste the XML requestdocument in a standard browser window and then view the XML response. The test harness isprovided 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 yourapplication (using Java, C++ or any other development language) to the actual LSt MLP 3.0.0interface.

The Openwave Location Studio test server is available to all members of the OpenwaveDeveloper Program. This test server, and the data contained within this server is provided for yourown 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 linkedto any person or business.

The test server is constantly maintained on a best efforts basis, but its availability is notguaranteed. If this site is not available for any reason, please send a message [email protected] 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:

"OPWV_MLP_extension_request.dtd">

%extension;

]>

theasp

thepwd

3033813000

12/15

http://loc2.openwave.com:8080/lst_test/client/mlp_servlet.htmlhttp://loc2.openwave.com:8080/lst_test/client/mlp_servlet.htmlhttp://72.165.137.101:14000/locationstudio/mlp300http://72.165.137.101:14000/locationstudio/mlp300mailto:[email protected]://loc2.openwave.com:8080/lst_test/client/mlp_servlet.htmlhttp://72.165.137.101:14000/locationstudio/mlp300http://72.165.137.101:14000/locationstudio/mlp300mailto:[email protected]:[email protected]://loc2.openwave.com:8080/lst_test/client/mlp_servlet.html


13/15

Zone

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

The test server does not support CURRENT. When sending requests to the test server, you mustspecify a loc_type other than CURRENT, such as CURRENT_OR_LAST. All live networkimplementations support CURRENT requests.

HTTP Post URL

The browser test harness described previously simply takes the XML and posts it to the actual MLP3.0.0 request interface of LSt. After you have verified your XML request is valid and you knowwhat 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 totest MLP with your client application.

Username/Password

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

infoservdemo1

infoservdemo1

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

! infoservdemo1! infoservdemo1

Test Data

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

! ! ! 3035551001

13/15

http://72.165.137.101:14000/locationstudio/mlp300http://72.165.137.101:14000/locationstudio/mlp300


14/15

! 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(DDD MMSS.sssH)

X(DDD MMSS.sssH)

Accuracyradius

L o c a t i o nAge

Code

303-555-1000Subscriber NotProvisioned

- - - - 6

303-555-1001T y p i c a l H i g h -Accuracy (AGPS)

1 0 5 1 602.675W

40 01 16.355N 20 < 10 min 0

303-555-1002Typical Cell-Sector(Urban)

1 0 5 0 236.445W

39 46 07.564N 300 < 10min 0

303-555-1003Typical Cell-Sector(Suburban)

1 0 5 0 253.858W

39 51 14.399N 1,000 < 10 min 0

303-555-1004Typical Cell-Sector(Rural)

1 0 5 1 607.154W

40 00 59.558N 10,000 < 10 min 0

303-555-1005Standard location 1 0 5 1 234.322W

39 45 15.778N 1000 < 10 min 0


40 00 00.000N 1000 < 10 min 0


40 21 12.726N 1000 < 10 min 0


40 31 30.910N 1000 < 10 min 0


40 07 24.437N 1000 < 60 min 0

303-555-1010Master PrivacyEnabled

1 0 5 0 724.452W

40 07 24.437N 1000 < 10 min 203

303-555-1011Monday Fridayonly

1 0 5 0 724.452W

40 07 24.437N 1000 < 10 min 0, or203

303-555-1012S a t u r d a y a n dSunday only

1 0 5 0 724.452W

40 07 24.437N 1000 < 10 min 0, or203

303-555-1013Standard location 1 0 5 0 7

24.452W

40 07 24.437N 1000 > 60 min 0, or

201

303-555-1014Client RelationshipDisabled

1 0 5 0 724.452W

40 07 24.437N 1000 < 10 min 0, or203

303-555-1015Client RelationshipNot Available

1 0 5 0 724.452W

40 07 24.437N 1000 < 10 min 0, or203

14/15



15/15

3) HOW DO I GET SUPPORT?

NII Developer Program provides support for integration with NIIs Location API. You may directquestions to [email protected], or visit

http://programa.nii.com.

The Openwave Developer Program provides support for the Openwave test server describedabove.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: [email protected]

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

15/15

http://developer.openwave.com/dvl/tools_and_sdk/location_studio/index.htmhttp://devforum.openwave.com/http://devforum.openwave.com/mailto:[email protected]:[email protected]://programa.nii.com/http://programa.nii.com/mailto:[email protected]:[email protected]://developer.openwave.com/dvl/tools_and_sdk/location_studio/index.htm

Date post:	30-May-2018
Category:	Documents
Upload:	kironbellerofontis
View:	217 times
Download:	0 times

Nii Lbs-lifmlp Development Guide

Documents