Android

Location-based Service APIs

The Android SDK includes two packages that provide Android's primary support for building location-based services: android.location and com.google.android.maps. Please read on below for a brief introduction to each package.

android.location

This package contains several classes related to location services in the Android platform. Most importantly, it introduces the LocationManager service, which provides an API to determine location and bearing if the underlying device (if it supports the service). The LocationManager should not be instantiated directly; rather, a handle to it should be retrieved via getSystemService(Context.LOCATION_SERVICE).

Once your application has a handle to the LocationManager, your application will be able to do three things:

  • Query for the list of all LocationProviders known to the LocationManager for its last known location.
  • Register/unregister for periodic updates of current location from a LocationProvider (specified either by Criteria or name).
  • Register/unregister for a given Intent to be fired if the device comes within a given proximity (specified by radius in meters) of a given lat/long.

However, during initial development, you may not have access to real data from a real location provider (Network or GPS). So it may be necessary to spoof some data for your application, with some mock location data.

Note: If you've used mock LocationProviders in previous versions of the SDK (m3/m5), you can no longer provide canned LocationProviders in the /system/etc/location directory. These directories will be wiped during boot-up. Please follow the new procedures below.

Providing Mock Location Data

When testing your application on the Android emulator, there are a few different ways to send it some spoof location data: with the DDMS tool, the "geo" command, or a Test Provider from the LocationManager. The latter requires modification to your location-aware code, the first two do not.

Using DDMS

With the DDMS tool, you can simulate location data a few different ways:

  • Manually send individual longitude/latitude coordinates to the device.
  • Use a GPX file describing a route for playback to the device.
  • Use a KML file describing individual placemarks for sequenced playback to the device.

For more information on using DDMS to spoof location data, see the Using DDMS guide.

Using the "geo" command

Launch your application in the Android emulator and open a terminal/console in your SDK's /tools directory. Now you can use:

  • geo fix to send a fixed geo-location.

    This command accepts a longitude and latitude in decimal degrees, and an optional altitude in meters. For example:

    geo fix -121.45356 46.51119 4392
  • geo nmea to send an NMEA 0183 sentence.

    This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data). For example:

    geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62

Using a Test Provider

You can also create a mock LocationProvider, called a Test Provider, within the LocationManager. This will allow you to programmatically update the LocationManager's perceived location.

To utilize a Test Provider, you should be aware of the following essential methods:

You must also declare the ACCESS_MOCK_LOCATION permission in your Android Manifest file. So add the following node as a child of the <manifest>:

<uses-permission android:name="android.permission.ACCESS_MOCK_LOCATION" />

When you create the Test Provider with addTestProvider(), you can pass any string you'd like to identify it. You then use this name for all subsequent Test Provider methods.

There are several other methods that allow you to further manage your Test Provider. See the LocationManager to learn more.

Note: By default, the LocationManager currently provides a single LocationProvider called "gps" that simulates a journey between two locations in the San Francisco Bay Area.

com.google.android.maps

This package introduces a number of classes related to rendering, controlling, and overlaying customized information on your own Google Mapified Activity. The most important of which is the MapView class, which automagically draws you a basic Google Map when you add a MapView to your layout. Note that, if you want to do so, then your Activity that handles the MapView must extend MapActivity.

Once you've created a MapView, you'll probably want to use getController() to retrieve a MapController, for controlling and animating the map, and ItemizedOverlay to draw Overlays and other information on the Map.

This is not a standard package in the Android library. In order to use it, you must add the following node to your Android Manifest file, as a child of the <application> element:

<uses-library android:name="com.google.android.maps" />

For a quick guide to creating your own MapView, see the Hello MapView tutorial.

Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48