Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

A guest post by Matthew Johnson, whose focus is in the mobile phone environment, primarily Android, and he can be reached at @epitygxanwn or at

The Android Map API v2 presents us with exciting possibilities far beyond what we could dream of under the Map API v1. Exciting new opportunities, however, tend to be accompanied by less exciting new difficulties as well. The Map API v2 is no exception. In this post, let’s see if details can help overcome these new difficulties.

The first thing the Android developer will notice is that to use the new API, you must include the Google Play Services. Read Publishing to Google Play in Introduction to Android Application Development: Android Essentials, Fourth Edition. If you are building for older phones (as you should), you must also include the Android Support library. Read Adding the Support Library to a Project in The Android™ Developer’s Cookbook: Building Applications with the Android SDK, Second Edition. Once you have these, then you can go to the Google API Console and get your Map API v2 key.

Note: Backwards compatibility is really important. Although few developers will feel the need to maintain backwards compatibility all the way back to 1.5 (‘Cupcake’ released in 2009), as of this writing, 96% of all phones connecting to Google Play are running one of three versions: Ice Cream Sandwich, Jellybean or Gingerbread.

The instructions for the above steps are described in detail at the following websites:

But before I go into how to make best use of the sites above, there is another sticking point I want to cover: the confusion over the terms location, geo-location and geocoding.

Yes, there really is confusion of these terms, especially on Stack Overflow, an excellent resource in many ways. Hence the need to clear these up once and for all.


This simply means any API/service having to do with the location of the phone. Most applications have to do with Google Maps, but there is more. Lots more.

Examples of Android classes for supporting location services are: Location, LocationProvider, LocationManager, LocationListener, CameraUpdate, LocationSource, MapView, MapFragment, GoogleMap, (these last five in the list are v2, so focus on these). Then there are the nested (sub)classes of GoogleMap, but I won’t list them here.


This is a term used by Google Android documentation to refer to coordinates entered in the emulator. The geo prefix emphasis that the location is specified in global, geographical coordinates, e.g. longitude and latitude in decimal degrees.

But the term geo-location is also used in a more general sense, to refer to the whole user experience of using location data to enhance a UI. So in this sense, it is nearly a synonym with location, but with an emphasis (again) on geographical scope of coordinates.

The same term is used with slightly different spelling (geolocation, not geo-location) to refer to permissions to use geolocation, i.e. the android.webkit.GeolocationPermissions object. But this is for use with JavaScript, not for use with the Android Map API v2.


This means a certain very specific location service: translating between street addresses and locations expressed as latitude/longitude in microdegrees. Or the same term is used somewhat more generically for translation in either direction, with forward being from street address to lat/long, and reverse being (obviously) from lat/long to street address.

The Android class for supporting geolocation services is Geocoder. The main and obvious helper class for it is Address.

Unfortunately, although Google does describe this class as “a simplified version of xAL”, it never gives a list of the simplifications. It does give a link to the xAL specification, which is somewhat helpful: CIQ hosted xAL spec.

Interestingly enough, you do NOT need to use either Map API to use Geocoding. This is handy for testing, though it is hard to come up with use cases for geocoding that do not involve maps.

Best Sites

Now for the promised details on “best use” of the sites above, I have some caveats:

  • The programmer needs to know at least the basics of Fragments, since MapFragment is so basic to Maps API v2.
  • At the time of this writing, the Google instructions are not quite up to date. For example, on three different systems running Juno or Indigo version of Eclipse and the latest versions of all Google tools, I could not follow the Google instructions on how to add a library: I had to open the project and add the libraries as external JARs to the Java Build Path instead, and then export them.
  • Make sure you are using the latest version of the ‘v4’ library: the ‘4’ in ‘v4’ is NOT the version of the library, we are currently on version 18 of the v4 library.
  • Maps API v2 is NOT supported on the emulator: not even the most recent one. And if you do try it there, the error message you get is NOT very helpful (some gibberish about not finding R$styleable), so don’t bother.
  • Keep track of which applications you have included in API Console. No point in wasting time tracking errors that turn out be because you did a new build of a modified version and forgot to include its package in API Console. Remember that the key depends upon the signing key, so if you develop on multiple systems, you have to either import the signing key to all of them or input multiple API keys in the API Console.
  • Android’s official documentation, examples, and third party documentation (including many excellent books on Android), often use slightly different terms for the Support Library. It is sometimes simply called “Support Library”, sometimes, “Android Support Library” or even “Android Support Library Package”. The older name for it (predominant in printed books) was “Compatibility Package”. Read 20.7. The Android Compatibility Package in Android in Action, Third Edition. The one you want is the Android Support Library Package, at this time a JAR file called android-support-v4.jar. For Maps v2 API, you do not need v7 or v13.

See below for more Android resources from Safari Books Online.

Read these titles on Safari Books Online

Not a subscriber? Sign up for a free trial.

Introduction to Android Application Development: Android Essentials, Fourth Edition covers the fundamentals of Android development in a format that is suitable for both professional and classroom use. This is your start-to-finish guide to the essentials for Android development, updated for the latest Android SDK.
Android in Action, Third Edition takes you far beyond “Hello Android.” You’ll master the SDK, build WebKit apps using HTML 5, and even learn to extend or replace Android’s built-in features. You’ll find interesting examples on every page as you explore cross-platform graphics with RenderScript, the updated notification system, and the Native Development Kit. This book also introduces important tablet concepts like drag-and-drop, fragments, and the Action Bar, all new in Android 3.
Expert Android gives you advanced techniques for customizing views, controls, and layouts. You’ll learn to develop applications in record time using JSON, Advanced Form Processing, and the BaaS (Backend As A Service) platform Parse. The book also includes extensive coverage on OpenGL, Search, and Telephony. With these advanced and time saving technologies you’ll be able to release compelling mobile applications in Google Play and the Amazon Appstore at a rapid pace.

About the author

matthewjohnson Matthew Johnson is widely experienced in developing both high and low level software (from device drivers and custom control of hardware up to high-level applications written in high level languages following object-oriented methodologies). His focus is in the mobile phone environment, primarily Android, and he can be reached at @epitygxanwn or at

Tags: android, Android Support Library Package, Geo-location, Geocoding, geolocation, Google Play, Location, Maps API v2,

Comments are closed.