Getting Started¶
This is a brief introduction to the Clearwire Location Platform (CLP).
- Overview
- Types of Location APIs
- Selecting a Clearwire Location API
- Using Parlay X API
- Using JSON/REST API
Overview¶
The Clearwire Location Platform (CLP) is a cell sector location system that interfaces with the existing Clearwire wireless network infrastructure to provide the location of devices within the network based upon the centeroid of the sector to which they are connected. A cell is typically divided into three sectors, thus, providing a higher level of precision than just the geodetic address (Lat, Long) of the tower.
The following diagram shows a high-level view of Clearwire’s location system.
The CLP provides location throughout entire cities, indoors and outdoors, with an initial accuracy of around 800 meters, improving to less than 100 meters with future developments. It also provides superior battery performance, a less than 1 second response time for requests, and support across a wider range of devices, such as PCs, laptops, netbooks, and mobile phones. With the CLP, you can develop Web pages, server-based applications, and custom applications on devices that will enable your customers to share their location, find the location of their friends, show their location on a map, contextualize local Web searches, and enhance advertising and other services.
Clearwire’s location platform is easier to use and more accessible to deliver a wider range of location-based services accessible via browsers, applications, devices, and servers. Besides supporting traditional location interfaces, the CLP takes advantage of the evolving World Wide Web Consortium (W3C) Location Framework and includes location into many of the latest browsers, so that any Web page can utilize a WiMAX location. This kind of accessibility is a big opportunity for the location industry to grow and Clearwire is there to support the effort.
Part of supporting this growth is opening up the business model to allow you to build out service ideas and have a chance to be successful. Clearwire offers a trial level of access to the CLP to allow you to explore new location services and is committed to enabling a business model where location can flourish as an integral part of any Web site or application. To learn more, please review the Location API Terms of Service.
This growth can only be achieved if the features and benefits of using location are clearly presented to the customer. Clearwire supports clear opt-in messaging to customers to ensure that they understand who is using their location and how they are using it. Clearwire wants to enable the ecosystem with a great location service, but everyone must do their part to ensure that the customer has a good experience. To learn more, please review Clearwire’s Privacy Policy at http://www.clear.com/company/legal/privacy.htm and the Location API Terms of Service.
Get information on the types of location APIs Clearwire offers.
Types of Location APIs¶
The CLP provides two APIs to access location information of devices on the Clearwire network:
- Parlay X
The Parlay X API is a SOAP/XML-based API that works with Web sites, custom applications, and server-based applications and services. With this API, you can make a proxy request from a server to retrieve current location information of your customers. If you are connecting to the CLP through a server-based service, the Parlay X API enables you to get current location remotely.
The Parlay X API requires a secure digital certificate-based authentication of the application server to access the CLP to ensure that only authorized services access location remotely.
For more information, see the Parlay X API Architecture and the Parlay X API Reference.
- JSON/REST
The JavaScript Object Notation (JSON/REST) API is a more scalable location interface that delivers location-based services more easily to a wider range of browsers, applications, and devices. The network-based JSON/REST interface offers direct access to the CLP through a browser, and is easy to use with a simple JavaScript request.
For more information, see the JSON/REST API Architecture and the JSON REST API Reference.
Select and decide on the type of Clearwire Location API you want to use.
Selecting a Clearwire Location API¶
You can choose the API based upon what you want your application to do. For example, suppose you want to develop a buddy list application, where not only do you want your customers to know their own location, but also the location of their friends on the buddy list. In such a case, you would use the Parlay X API so you could access location information from your server for multiple customers, periodically.
In another instance, suppose you want to have your customers’ location automatically known by a Web site or application so that they can get real-time weather information and find places of interest in their area based on their position. In this case, you would use the JSON/REST API, which allows direct access to location information through the Clearwire network without going through an application server.
The following table provides guidelines that you can use to select an API that best suits your development needs.
| Use Parlay X if… | Use JSON/REST if… |
|---|---|
| You want a more high-involvement relationship with your customer, including accessing location remotely. | You want your users to get location information about themselves only. |
| You want to location-enable your Web page and need support from all browsers. | You want to more easily location-enable your Web site by adding two lines of JavaScript, and you are not deterred by a lack of native browser support at this early stage of the W3C location standard. |
| Your application is focused on using a WiMAX location. | You want a location solution that enables WiMAX and other location service providers for different network setups, such as WiFi, Ethernet, 3G, etc. |
Next Steps to Using Clearwire Location APIs¶
- Create and customize your Web page, server, or application to access the CLP and request location information. For API information, see the specific API Reference page.
- (Optional) Understand the architecture of the API you selected.
- Test your Web page, server, or application for connectivity. For more information, see the section on how to use the API you selected.
Using Parlay X API¶
The Clearwire Parlay X API is a subset of the Parlay X 3.0 Part 9 Terminal Location Service standard. This specification is part of the ParlayX suite of standards published by the European Telecommunications Standards Institute (ETSI). The Terminal Location Service is available only using SSL/TLS transport with client certificate authentication.
To use the Parlay X API, you must first create an application server that can authenticate and request location information from the CLP. Clearwire will assign you an application ID that you use in conjunction with the certificate for authentication. For Parlay X API information, see the Parlay X API Reference page.
After you have created and customized your application server, you can test it to verify that it connects to a test CLP and retrieves a location.
Your application server can remotely find the location of your users by passing their identity, such as a MAC address or their current IP address to the CLP. The CLP then finds their location and passes it back to your application server for any location-customized display.
Your application can also reside on a client device and get your own location directly from the CLP.
Requirements¶
Before you can use your application server to access the CLP, make sure that you contact Clearwire to obtain an authentication certificate. For more information, see the Parlay X Resources and Tools page.
Connecting to the Location Platform¶
After you have created and customized your application server, you should test it by making sure that it successfully connects to a test CLP.
To connect to a test CLP, include the following URL in your application: "https://testlocation.clearwire-wmx.net:8443/parlay/services/TerminalLocationService"
For Parlay X API information, see the Parlay X API Reference page.
Finding a Location¶
After you have connected to the CLP, you should test your application server to verify that it finds your location, as well as the location of other users in your area.
To retrieve a location:- Make sure that the device for which you want location is connected to the WiMAX network.
- Open the application that you created.
The application communicates with the CLP and passes on the device’s identity (MAC address or current IP address). CLP finds the location for the device and returns it to your application.
Using JSON REST API¶
The JSON/REST API uses the Google Gears Geolocation API to request the location of a device on the Clearwire WiMAX network. For information on Google Gears, go to http://code.google.com/apis/gears/.
With the JSON/REST API, you can connect directly to the CLP through a Gears-enabled Web browser using JavaScript. 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. For browser source code examples, see the JSON REST API Reference page.
This first implementation supports only those browsers with Google Gears installed into them. Currently, only Google Chrome and the Android browser have Gears built in natively. For browsers that do not have Google Gears installed, a user can go to http://gears.google.com/ to download Gears.
Clearwire will continue to work with the W3C and browser companies on the evolving location standard to get native browser support for the CLP, so that all users can seamlessly utilize a location while connected to the Internet.
With the JSON/REST API, you can also connect to the CLP 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. For an example of how to write an application using the JSON/REST API, go to http://community.4gdeveloper.com/wiki/lbs/LBS_Search_Tool. For JSON libraries that you can use to write your custom application, go to http://JSON.org.
After you have created and customized your Web page or application to obtain a position from the CLP, you can test it to verify that it connects to a test CLP and retrieves a location.
Currently, Clearwire is testing the JSON/REST API for usage and functionality. Clearwire will continue to enhance and improve upon JSON/REST API functionality based on developer feedback.
To see a live demo showing the use of both Clearwire and Google location services to retrieve current location, go to http://developer.clear.com/ClearLocationDemo.html. You must be connected to the Clearwire WiMAX network and use a Gears-enabled Web browser to enable the demo.
Requirements¶
Before you can use the JSON/REST API, make sure that you do the following:- For browser access to the CLP, use a browser that has Google Gears built in natively, such as Google Chrome and the Android browser; for all other browsers, go to http://gears.google.com/ to install Gears.
- If using a custom application to access the CLP, have Google Gears installed and activated on the device(s) you will use on the Clearwire Broadband service. To install Google Gears, go to http://gears.google.com/.
Connecting to the CLP¶
After you have developed and customized your Web page or application to obtain a position from the CLP, you should test it by making sure that it successfully connects to a test CLP.
To connect to a test CLP, include the following URL in your Web page or application: "http://testlocation.clearwire-wmx.net:8000/json/"
For JSON/REST API information, see the JSON REST API Reference page.
Finding a Location¶
After you have connected to the CLP, you should test your Web page or custom application to verify that it finds your location.
To find a location:- Make sure that the device for which you want location is connected to the WiMAX network.
- Open a Gears-aware application (for example, Web page) that requests current location from Google Gears.
The CLP automatically determines your location and delivers it to the application being viewed via Google Gears.
Next Topics
- Architecture
- Parlay X API Reference
- JSON REST API Reference
- Resources and Tools