Using the Adobe AIR Geolocation APIs on Android
Created
10 October 2011
Requirements
Prerequisite knowledge
User level
Intermediate
Required products
- Flash Builder (Download trial)
- Flash Professional CS5 (Download trial)
Sample files
The Geolocation API provides a high-level interface to access the geographical location information of the device. The geographical location can be displayed on the device in the form of latitudinal and longitudinal coordinates. The API is designed to enable both one-shot location request and repeated location updates (useful while building a Geo tracking application). This example shows you how you can get repeated location updates in your application.
In your Android device, when the location of the device changes, your application can receive updates about the changes, including information on altitude, accuracy, heading, speed, and timestamp using one of the following location sources:
- GPS Satellites: Enables accurate positioning if a GPS sensor is available.
- Wireless networks: Enables approximate positioning if a data connection is available.
The Geolocation API provides the necessary support to build applications, which uses the location sources configured in the device.
In this article, you will learn about:
- The Geolocation API
- Handling Geolocation events in your application
- Android-related device permissions
- Troubleshooting your application
Handling Geolocation events
To build Geolocation-based applications, use the following classes:
-
flash.sensors.Geolocationto initilialize location sensor in your device. -
flash.events.GeolocationEventto get location information at defined intervals.
To find out if the device supports Geolocation at all, use the Geolocation.isSupported property. This property is false on devices that do not have geolocation capabilities. This property will also return false in an Android emulator, even when you simulate the Geolocation functionality with the Android Emulator's geo fix command, and hence this example will not work in an Android emulator.
The following code initializes your device's location sensor and adds an event listener to get regular location updates from the device:
if (Geolocation.isSupported)
{
//Initialize the location sensor.
geo = new Geolocation();
if(! geo.muted){
geo.setRequestedUpdateInterval(60000);
//Register to receive location updates.
geo.addEventListener(GeolocationEvent.UPDATE, geolocationUpdateHandler);
}
}
In the previous example, the time interval for getting location updates is set to 60000 milliseconds (1 minute). You should choose the longest update interval that satisfies your application requirements.
Note: If you do not set the setRequestUpdateInterval property, the device will return the location updates based on the default interval set in the device. To conserve battery power, it is always advisable to provide a longer update interval.
The application can stop performing other activities if the location sources are not available by reading the muted property of the Geolocation class:
if(geo.muted){
//Display an error message or halt the application.
}
In the geolocationUpdateHandler function, use the GeolocationEvent's properties to get the location information:
private function geolocationUpdateHandler(event:GeolocationEvent):void
{
geoLat.text = "Latitude: " + event.latitude.toString();
geoLong.text = "Longitude: " + event.longitude.toString();
geoAccu.text = "Accuracy: " + event.horizontalAccuracy.toString();
geoSpeed.text = "Speed: " + event.speed.toString();
}
The Geolocation attributes
Table 1 shows the Geolocation attributes reported by the GeolocationEvent object.
Table 1. Geolocation properties of the GeolocationEvent object
| Attribute | Description | Unit |
|---|---|---|
latitude |
The geographical coordinate with a value between –90 to +90 degrees. Negative latitude denotes south and positive latitude denotes north. | Degrees |
longitude |
The geographical coordinate with a value between –180 to +180 degrees. Negative longitude denotes west and positive longitude denotes east. | Degrees |
altitude |
Vertical height of the geographical coordinates (Latitude and Longitude). | Meters |
horizontalAccuracy (Accuracy) |
The horizontal accuracy of the position denoted by the geographical coordinates (Latitude and Longitude). | Meters |
verticalAccuracy (Altitude Accuracy) |
The vertical accuracy of the position denoted by the geographical coordinates (Latitude and Longitude). | Meters |
speed |
The current ground speed of the device. If the device is stationary, the value of this attribute will be zero. | Meters/Seconds |
timestamp |
The time since the application was initialized. For example, if the application has captured geolocation data for four seconds after it got initialized, then the value of this attribute will be 4000. | Milliseconds |
Note: Although the Heading Geolocation attribute is available through the API, it is not yet supported in the Android devices. The Heading attribute will always return NaN (Not a Number) in an Android application.
Declaring Android permission
For your application to work, you need to specify the necessary Android permission in the application descriptor file under the <android> element.
<android>
<manifestAdditions>
<![CDATA[<manifest>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> </manifest>]]>
</manifestAdditions>
</android>
Note that the ACCESS_FINE_LOCATION Android permission is required by the application to use the device's GPS sensor.
Troubleshooting your application
When your application does not return any value for the Geolocation attributes, it could be because of one or more of the following issues:
- The Geolocation event does not get dispatched. This issue is primarily due to the lack of GPS fix. For a successful GPS fix (GPS device getting connected with four or more satellites), the device should have a clear view of the sky. In an enclosed space, getting a GPS fix in your device is difficult. If you do not need accurate position information in your application, you can use the network-based Geolocation that will rely on the wireless network to get an approximate position of your device. If your application uses the network-based Geolocation, check if your device is configured to send and receive data through a valid Internet APN (Access Point Name). To check if you have configured an Internet APN, go to Settings > Wireless and Networks > Mobile Network > Access Point Names and look for the default entry (the one with a green icon, shown in Figure 2).
Figure 2. Checking the Internet APN configuration.
- GPS is muted. GPS should be enabled if you want to get the position information based on the GPS satellites. In most of the Android phones, the option will be under Settings > Location and Security Settings > My Location sources.
Figure 3. Checking whether GPS is enabled.
You can enable both GPS-based and network-based location sources so that if the GPS fix does not happen, your AIR application will try to use the network-based location source (if data connection is available).
- Android permission issue. You need to specify the
ACCESS_FINE_LOCATIONAndroid permission as discussed in the "Declaring Android permission" section above. TheACCESS_FINE_LOCATIONpermission is required to access GPS location data. EitherACCESS_FINE_LOCATIONorACCESS_COARSE_LOCATIONis required to access wireless network location data. - Code issue. Check if you have declared the Geolocation object globally in your application. If the Geolocation object is declared locally (inside a method), chances are that the object may get garbage collected. For example, the following code may not work properly because the Geolocation object is declared and initialized inside a method.
public function locateMe()
{
Geolocation geo = new Geolocation();
...
}
private var geo:Geolocation;
public function locateMe()
{
geo = new Geolocation();
...
}
If you still face any issue getting the Geolocation API to work in your application, post your issue in the AIR for Android developer forum.
Where to go from here
In this example, you have learned how to use the AIR Geolocation APIs for your Android applications. You can use these Geolocation APIs to build simple-to-complex Android applications involving navigation, speed monitoring, and GPS-based route tracking.
For more information, refer to the following resources:
This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License
