Advertisement
Android SDK

Android SDK: Working with Google Maps - Application Setup

by

The Google Maps API for Android provides developers with the means to create apps with localization functionality. Version 2 of the Maps API was released at the end of 2012 and it introduced a range of new features including 3D, improved caching, and vector tiles. In this tutorial series, we will create an app that uses Google Maps for Android V2 in conjunction with the Google Places API. The app will present a map to the user, mark their current location and nearby places of interest, and will update when the user moves.

This tutorial series about Using Google Maps and Google Places in Android apps will be presented in four parts:

The processes required to integrate Google Maps and Google Places with Android apps are relatively complex and not suitable for beginners, so for the purposes of this tutorial it is assumed that readers have already completed at least a few basic apps in Eclipse.

This is a snapshot of the final app:

App We Are Working Towards

1. Integrate Google Play Services

Step 1

Google Maps Android API V2 is part of Google's Play services SDK, which you must download and configure to work with your existing Android SDK installation in Eclipse to use the mapping functions. In Eclipse, choose Window > Android SDK Manager. In the list of packages that appears scroll down to the Extras folder and expand it. Select the Google Play services checkbox and install the package.

SDK Manager

Step 2

Once Eclipse downloads and installs the Google Play services package, you can import it into your workspace. Select File > Import > Android > Existing Android Code into Workspace then browse to the location of the downloaded Google Play services package on your computer. It should be inside your downloaded Android SDK directory, at the following location: extras/google/google_play_services/libproject/google-play-services_lib.

Import Package

2. Get a Google Maps API Key

Step 1

To access the Google Maps tools, you need an API key, which you can obtain through a Google account. The key is based on your Android app debug or release certificate. If you have released apps before, you might have used the keytool resource to sign them. In that case, you can use the keystore you generated at that time to get your API key. Otherwise you can use the debug keystore, which Eclipse uses automatically when you generate your apps during development.

The API key will be based on the SHA-1 fingerprint from your debug or release certificate. To retrieve this you will need to run some code on the Command Line or in a Terminal. There are detailed instructions in the Google Developers Maps API guide for different operating systems and options. The following is an overview.

To use the debug certificate stored in the default location, run the following in a Terminal if you're on Linux:

keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

You will need to alter the path to the debug keystore if it's in a different location. On the Windows Command Line use the following for the default location, amending it to suit your C-Drive user folder:

keytool -list -v -keystore "C:\Users\your_user_name\.android\debug.keystore" -alias androiddebugkey -storepass android -keypass android

If you want to use a release certificate, you first need to locate your release keystore. Use the following to display the keystore details, replacing "your_keystore_name" with the path and name of the keystore you are using:

keytool -list -keystore your_keystore_name

You will be prompted to enter your password, then you should see the aliases associated with the keystore. Enter the following, amending it to reflect your keystore and alias names:

keytool -list -v -keystore your_keystore_name -alias your_alias_name

Whether you're using a debug or release certificate, you will be presented with several lines of output. Look for the line beginning "SHA1" in the "Certificate fingerprints" section; it should comprise 20 HEX numbers with colons between them. Copy this line and append your app's intended package name to the end of it, storing it for future reference. For example:

BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75;your.package.name

Step 2

Now you can use your certificate SHA-1 fingerprint to get an API key for Google Maps. Sign into your Google account and navigate to the APIs Console. If you haven't used the console before it will prompt you to create a project.

APIs Console

Go ahead and create one, then rename it if you wish by selecting the drop-down list in the top left corner, which may have the default name "API Project" displayed on it.

Rename Project

Choose Rename and enter your chosen project name, which does not matter for the purposes of this series.

Project Name

Step 3

The APIs console manages access to many Google services, but you need to switch on each one you want to use individually. Select Services from the list on the left of the APIs console. You should see a list of Google services, scroll down to Google Maps Android API V2 and click to turn it on for your account.

Switching Maps API On

Follow the instructions to agree to the API terms.

Step 4

Now we can get a key for the app. Select API Access on the left-hand-side of the API console. You may already see a key for browser apps, but we need one specifically for Android apps. Near the bottom of the page, select Create new Android key.

Create a New Android Key

In the pop-up window that appears, enter the SHA-1 fingerprint you copied from your certificate (with your package name appended) and click Create.

Enter the Fingerprint

The API Access page should update with your new key. In the new Key for Android apps section, copy the key listed next to API key and store it securely.

Tip: If you decide, for example, to use the debug certificate at first and then the release certificate, you will need to obtain a separate API key for the release certificate- just follow the same process with the SHA-1 fingerprint for your release certificate when you are ready.

3. Create an Android App

Step 1

We are finally ready to create an app! In Eclipse, create a new Android Project (File > New > Project > Android Application Project). Enter your chosen package and application names. Remember the package name you used to generate the Maps API key. In the source code, download the target SDK version 17 with a minimum of 12. Let Eclipse create a blank Activity for you. In the download we use MyMapActivity and activity_my_map for the layout.

Step 2

Although we added the Google Play services package to the Eclipse workspace, we still need to setup this particular app to use it. Select your new project in the Eclipse Package Explorer and configure its Properties (right-click > Properties or Window > Properties with the project selected). Select the Android tab and scroll to the Library section, then choose Add.

Project Properties

Select the Google Play Services library to add it to your project.

Play Services Library

Choose Apply before exiting the Properties window.

Library Added

4. Get Ready for Mapping

Step 1

Now we can get the app ready to use mapping functions by adding the appropriate information to the Project Manifest file. Open it and switch to the XML tab to edit the code. First let's add the Google Maps API key inside the application element, using the following syntax:

<meta-data
	android:name="com.google.android.maps.v2.API_KEY"
	android:value="your_key_here" />

Include your own API key as the value attribute.

Step 2

Now we need to add some permissions to the Manifest. Inside the Manifest element but outside the application element, add the following, amending it to include your own package name:

<permission
	android:name="your.package.name.permission.MAPS_RECEIVE"
	android:protectionLevel="signature" />
<uses-permission android:name="your.package.name.permission.MAPS_RECEIVE"/>

The Maps API is associated with lots of permissions, the need for which of course depends on your own app. The Developer Guide recommends adding the following to any app using Maps:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Finally, we need to add a feature element for OpenGL ES version 2:

<uses-feature
	android:glEsVersion="0x00020000"
	android:required="true"/>

5. Add a Map to the App

Step 1

At last we are ready to include a map in the app. Open your app's main layout file. Replace the contents with the following:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
	xmlns:map="http://schemas.android.com/apk/res-auto"
	android:id="@+id/the_map"
	android:layout_width="match_parent"
	android:layout_height="match_parent"
	android:name="com.google.android.gms.maps.MapFragment"
	map:cameraTilt="45"
	map:cameraZoom="14"
	/>

This is a Map Fragment. We give it an ID so that we can identify it in Java and provide (optional) initial values for camera tilt and zoom. You can specify lots of settings here, including latitude/longitude, bearing, and map type, as well as toggling the presence of features such as compass, rotation, scrolling, tilting, and zooming. These options can also be set from Java.

If you let Eclipse create your main Activity class, it should already have the following code in the onCreate method. If not, add it now:

protected void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
	setContentView(R.layout.activity_my_map);
}

Alter the layout name if necessary.

Step 2

At this point you can run your app. You will need to run it on an actual device, as the the emulator does not support Google Play services. Provided that the necessary resources are installed on your test device, you should see a map appear when the app runs. By default, the user can interact with the map in more or less the same way they would with the Google Maps app (rotating, etc.) using multi-touch interaction.

App Initial Appearance

Conclusion

In this tutorial we created an app capable of using Google Maps Android API V2. Don't be put off by the complexity of the setup process, as the Java coding itself is not particularly complex. In the following tutorials, we will use the Google Map object to control display and interaction with the map. We will get another API key, this time for the Google Places API. After we retrieve the user location and mark it on the map, we will retrieve information about nearby places of interest, process these results, and mark them on the map as well. Throughout this series we will run through the basics of using Google Maps and Google Places within Android apps, outlining options for further development that you can explore in a wide variety of app types.

Related Posts
  • Code
    Android SDK
    Integrating Google Play Services on Android85ude preview image@2x
    By integrating your Android apps with Google Play Services, you can access Google services, such as Maps, Drive, and Google+. In this tutorial, we will go through the process of integrating Google Play Services with Android apps.Read More…
  • Code
    Android SDK
    Using New Relic to Monitor Your Android AppGetting started new relic retina preview2
    In the last two years, New Relic has focused hard on building out a solution for monitoring the performance of mobile apps. In this tutorial, we will look at how you can start using New Relic to monitor the performance of an Android application.Read More…
  • Code
    Android SDK
    Create a Music Player on Android: Project Setup0d63m preview image@2x
    The Android platform provides resources for handling media playback, which your apps can use to create an interface between the user and their music files. In this tutorial series, we will create a basic music player application for Android. The app will present a list of songs on the user device, so that the user can select songs to play. The app will also present controls for interacting with playback and will continue playing when the user moves away from the app, with a notification displayed while playback elapses.Read More…
  • Code
    Android SDK
    Android SDK: Publishing and ReleasingAndroid preview@2x
    From the start of this series, we've been learning about creating Android applications. So far, we've focused on the development aspect as well as the tools you use to design, build, run, and test your applications. In this tutorial, we'll look at the process of distributing an application through the Google Play store. Of course, you need to make sure that your applications have been tested and debugged thoroughly before you get to this stage.Read More…
  • Code
    Android SDK
    Android SDK: Common Android ComponentsAndroid preview@2x
    In this series we are learning the essential features of Android development that you need to know to start building apps. So far, we've looked at the structure and typical elements in an Android app, including user interface elements and data storage. You can use what we covered already to start creating your own apps. But before you do, we will run through some common Android components in this tutorial, then have a quick look at the SDK samples in the next tutorial.Read More…
  • Code
    Android SDK
    Android SDK: Project ManifestAndroid preview@2x
    In this series of tutorials we are learning about Android development from scratch and getting acquainted with the basic concepts and practices you need to know in order to start working on the platform. So far we have looked at various parts of an Android project, including its resources. In this tutorial, we will explore the project manifest file.Read More…