Android SDK Quick Tip: Launching Maps In-App

This Quick Tip will show you how to programmatically launch in to the Google Maps application. You will learn to load Maps with a precise position, a location name, and with a search query. As a bonus tip, you’ll see how to load a Street View at a particular location, with the “camera” aimed the direction you want.

Step 1: Preparation

We’ll begin this tutorial using the Phrasebook application we last built upon in the Enabling the Android “Move To SD Card” Feature tutorial on this site. The Phrasebook application displays some text and images based upon the user’s locale setting. One of these images is a map-a perfect place to try this tip. If you’d like to follow along, you can download the source code from that tutorial. The final code is also available on Google Code Hosting.

Step 2: Adding the Click Handler

We begin by adding a click handler to the existing ImageView that displays a map image based upon the user’s locale. In the PhrasebookActivity.java class file, add the following code within the onCreate() method:


ImageView map = (ImageView)findViewById(R.id.ImageViewMap);
map.setOnClickListener(new OnClickListener() {
    @Override
    public void onClick(View v) {
        // TODO: start map Activity here
    }
});

Step 3: Starting the Map Activity

Next, add some code to the click handler to read the location we want to display and send that data off to the Maps application. To do this, you can simply read the string resource, which will get a locale-specific string. (We’ll be adding the string resources in Steps 4-7.) Then use the specially-formatted string to create the appropriate Intent. Finally, use the Intent to launch the Maps app with a call to the startActivity() method, like so:


String geoUriString = getResources().getString(R.string.map_location);
Uri geoUri = Uri.parse(geoUriString);
Intent mapCall = new Intent(Intent.ACTION_VIEW, geoUri);
startActivity(mapCall);

In this way, when the user clicks the back button, they’ll be returned to the previous Activity. In this case, it’s your Activity so the user will be right back where they started. This is a great example of one of the advantages of the Activity model that Android uses.

Step 4: Displaying Maps by Latitude and Longitude

The Phrasebook application is now set up to load location resource strings and display the Map in the appropriate location. Let’s take things a step further by providing latitude, longitude and a zoom level value. For example, you could create a location string resource with the following location data:

1
2	<string name="map_location">geo:0,180?z=1</string>

This data will load up the Map at a latitude of 0 (the Equator) and a longitude of 180 (middle of the Pacific). The map will be zoomed all the way out, so it’ll show the whole world:

Step 5: Displaying Maps by Location Name Query

In addition to fixed-point locations, the Maps application can be launched to locations by name. The Maps application has support for a variety of different location name formats (addresses, countries, cities, landmarks, etc.). You should, however, remember that some names are quite ambiguous. For the Phrasebok application, it makes sense to seed the map using the country’s name.

For example, set the value to the map_location string in the French-speaking Belgium regional string resource file (values-fr-rBE/strings.xml) to:

1
2	<string name="map_location">"geo:0,0?q=Belgium"</string>

Here, we searched for a country name. When launched, the Maps application will display the appropriate region of the world: Belgium!

As we said, location names can be landmarks. For example, you could add the following location data to the Swiss-French string file (values-fr-rCH/strings.xml):

1
2	<string name="map_location">"geo:0,0?q=Matterhorn&z=8"</string>

Again, the Maps application displays the appropriate map location--that of the Matterhorn in the Swiss Alps.

Note the placeholder values for latitude and longitude within the queries. This is simply part of the format of the request. A specific street address will also work with these queries.

Step 6: Displaying Maps with a Search Query

In typical Google Maps fashion, we can also do a search for places of interest within a certain vicinity. For example, we could add the following map query to the French/France string resource file (values-fr-rFR/values.xml):

1
2	<string name="map_location">"geo:0,0?q=Coffee Shops near Paris, France"</string>

This query tells the Maps application to center the map in Paris, France and search for nearby coffee shops. Google Maps uses its own algorithms for deciding which shops to display. The user can drill down to see more shops.

Step 7: Displaying a Location with Street View

Finally, you can also display the Street View at a particular location, if one exists. This next string goes in French Canadian string resource file (values-fr-rCA/strings.xml):

1
2	<string name="map_location">"google.streetview:cbll=46.813812,-71.207378&cbp=1,99.56,,1,-5.27&mz=21"</string>

This location data tells the Maps application to display the Street View of the gardens along Rue des Jardins in Old Quebec:

The street view query needs a little more explanation. Street View is actually a different application from the Maps application on Android. The data passed to it matches the named parameters of the web version of Google Maps. The cbll parameter contains the the latitude and longitude information while the cbp parameter allows for some further Street View configuration:

1
2	1,yaw,,pitch,zoom

The yaw controls the direction you look in degrees clockwise from north and the pitch is in degrees from level, where up is negative (so 90 is looking straight down). The zoom is a multiplier, so 3 is a 3x zoom. The 1 and the double commas are required, but unused. Finally, the mz parameter provides the map zoom factor in case the user clicks on the “Go to Maps” option within Street View application. The easiest way to get the cbp parameters you desire is by using Google Maps in a regular web browser, navigating to the appropriate location and view, and extracting the Street View parameters from the link you can create to get to that location.

Conclusion

You now have the tools you need to easily launch in to the Google Maps or Street View applications on an Android device. You can load the map with a specific location, view a location by it’s name or address, and even perform a search near a location. Finally, you can load the Street View application to show a particularly interesting area of the world and adjust how it appears to users.

About the Authors

Mobile developers Lauren Darcey and Shane Conder have coauthored several books on Android development: an in-depth programming book entitled Android Wireless Application Development and Sams TeachYourself Android Application Development in 24 Hours. When not writing, they spend their time developing mobile software at their company and providing consulting services. They can be reached at via email to androidwirelessdev+mt@gmail.com, via their blog at androidbook.blogspot.com, and on Twitter @androidwireless.