Architecture¶
This is an architectural description of the Clearwire Location Platform (CLP) application programming interfaces (APIs).
Overview¶
The Clearwire Location Platform (CLP) is one of the key elements of the Clearwire network. It receives location requests for specific mobile stations, or mobile devices, and communicates with the appropriate infrastructure elements to identify the location for the mobile station. The user-facing interface uses two types of APIs to exchange location requests and responses, depending on the development needs of an organization:- Parlay X API
- JSON/REST API
At this time, the uncertainty of the location is half the radius of a WiMAX sector, which is around 800 meters. The location corresponds to the centroid of the sector in which the mobile station is located. While the accuracy of the location is coarse, the latency for such a location fix is under one second at all times. Additionally, the network architecture includes redundancy at a local, as well as a geographic level.
Parlay X API¶
The Parlay X API is the European Telecommunications Standards Institute (ETSI) standard for Open Service Access. It uses the Simple Object Access Protocol (SOAP) specification for its Web service and relies on an XML schema to access the CLP. This API supports a subset of the Parlay X 3.0 Part 9 Terminal Location Service.
Architectural View¶
The following diagram shows the general flow of information between the CLP and the Application Server using the Parlay X API.
An Application Server is any application that wants to know the mobile station’s location. The Application Server uses the Parlay X API to query the CLP by providing the mobile station’s identity—either a MAC or IP address. The CLP then processes the identity sent by the Application Server and finds the location of your device or other users, remotely.
The Application Server uses the location information received in the location response to render its application. The response from the CLP includes the geodetic address (Lat, Long) of the user.
Application Layer Security¶
Because location is of high importance and you want to find the location of other users, the Parlay X API requires secure mutual certificate authentication of the application server to access the CLP. Certificate-based authentication ensures that only authorized services access location remotely.
A certificate signed by Clearwire is given to the Application Server, which the client uses to authenticate the CLP. The Application Server, in turn, authenticates the certificate sent by the CLP.
To authorize the Application Server, the Application Server provides a valid application ID as part of its request. These credentials are authorized against the list of valid credentials on the CLP to allow access.
Call Flow¶
The following sequence diagram gives a high-level overview of the request-response call flow when using the Parlay X API to access the CLP.
JSON REST API¶
The JavaScript Object Notation, or JSON/REST, API enables users to access the CLP from any browser without requiring digital certificate-based authentication. Because the JSON/REST API is browser-based, it offers the ease and flexibility of connecting to the CLP from multiple locations without relying on a client application.
The JSON/REST API is a lightweight, text-based data structure. You use the Google Gears Geolocation API to enable Clearwire’s location-based services (LBS). LBS refers to location information that is derived from a device hosted on the Clearwire network by using the location of the tower with which the device is associated. LBS give you value-added services such as targeted advertising and potentially enhanced location services.
With the JSON/REST API, you can access the CLP in two ways:- Through a Gears-enabled Web browser using JavaScript. In this case, you will only need to customize your Web browser to include the service end point that connects your Web page to the CLP. For information on the JavaScript API used to access the CLP, see the JSON REST API Reference page.
- Through a custom application on a device using the Google Gears Geolocation API Network Protocol . For information on the Geolocation API Network Protocol used to access the CLP, see the JSON REST API Reference page.
Because the Google Gears framework is used, you are able to access the CLP in a more standardized manner based on recommended protocols. Standardization allows applications to obtain an accurate WiMAX location.
Architectural View¶
The following diagram shows the general flow of information between the CLP and the client using the JSON/REST API.
A Web browser or an application on the device uses the JSON/REST API to query the CLP to obtain the device’s location. The CLP determines if the request is coming from a Clearwire WiMAX network. Based upon that, the CLP retrieves a location for the user and provides it to the requesting device. The response from the CLP includes the geodetic address (Lat, Long) of the user and the street address, if requested.
Call Flow¶
The following sequence diagram gives a high-level overview of the request-response call flow when using the JSON/REST API to access the CLP.
Next Topics
- Parlay X API Reference
- JSON REST API Reference
- Resources and Tools
- Getting Started