Advertisement
News

This is How You Use the Google Maps API - screencast

by

So your client emails you and asks, "Can you put one of those flashy maps on my contact page so that users can actually see our building from a satellite's view?". You've used Google maps many times, but there is only one problem: you have no idea how to use the API. Well get out your spoon and dig in!

* Click on the full-screen toggle.

Step 1: Obtain a Unique API Key

If you were to download the source code that is provided with this article, you would find that it doesn't work on your website. The reason is because Google requires all users to obtain a unique "API key" for each site that implements Google maps.

Never fear. It's 100% free and takes about thirty seconds to sign up. First, visit Google's sign up page and enter the url of your website. Don't worry about adding a specific path. The root url will cover every page that is part of that domain. Agree to the terms and conditions and click "Generate API".

Generate Key

That's it! The page that you've been redirected to contains your unique key as well as a sample page - to serve as a crash course. Your key will look something like:

ABQIAAAAAq93o5nn5Q3TYaaSmVsHhR1DJfR2IAi0TSZmrrsgSOYoGgsxBSG2a3MNFcUDaRPk6tAEpdWI5Odv

You'll also find a script path that will look like:

<script src="http://maps.google.com/maps?file=api&v=2ampkey=ABQIAAAAAq93o5nn5Q3TYaaSmVsHhR1DJfR2IAi0TSZmrrsgSOYoGgsxBSG2a3MNFcUDaRPk6tAEpdI5Odvw" type="text/javascript"></script>

Yours will be different from mine because it will contain your own specific key value. Copy this and paste it into the head portion of your document.

Sign Up Complete

You might want to bookmark the link to the API documentation. You'll undoubtedly be referencing it as your skills progress.

Step 2: Setting Up Your HTML

For the sake of simplicity, we'll create a bare bones layout. Add the following within the body element of your document.

In a real world situation, you should move the styling to an external file (like I did in the video). The height and width values will by used by the API to determine the dimensions of your map. Don't worry, nothing will be clipped off.

Step 3: Javascript

Next, add the following to your Javascript file. Review it a bit and then continue on.

$(function() { // when the document is ready to be manipulated.
  if (GBrowserIsCompatible()) { // if the browser is compatible with Google Map's
    var map = document.getElementById("myMap"); // Get div element
    var m = new GMap2(map); // new instance of the GMap2 class and pass in our div location.
    m.setCenter(new GLatLng(36.158887, -86.782056), 13); // pass in latitude, longitude, and zoom level.
  }
else {alert("Your browser is not worthy.");}
});

To take this code line by line:

  • When the document is ready to be manipulated, run the code within.This is a jQuery syntax, but jQuery isn't required in the least. You could also simply add an "onLoad()" attribute to your body element - though this is messy.
  • If the browser that the user is accessing the map from isn't compatible with the API, then show an alert (see bottom). Otherwise, run the code within.
  • Create a variable called "map" and tell it to find the div that will contain the map.
  • Next, create a variable called "m" and make it equal to a new instance of the "GMap2" class. Within the parenthesis, pass in the "map" variable that you just created previously
  • Finally, set a center point so that the map knows what to show. To do this, we create a new instance of the "GLatLng" class and pass in the latitude and longitude values. You can go here to grab the appropriate values. In my case, I've set the coordinates to my home town. After that, you can optionally input a zoom level - which I've set to the standard '13'.

This code alone will give you a basic map that might be completely appropriate for your needs. However, if you'd like to also implement "zoom" and "map mode" features, read on.

Step 4: Refining Our Map

There are literally dozens of features that you can add to your map. We'll go over a few of them. First, we'll implement a zoom bar that will allows the users to incrementally zoom in or out.

Layout
m.addControl(new GLargeMapControl())

Here, we're taking our map and are adding a new control called "GLargeMapControl".

Next, let's add a feature that will allow the users to choose which map mode they desire - Normal, Satellite View, or a hybrid.

var c = new GMapTypeControl(); // switch map modes
m.addControl(c);
  • Create a variable called "c" and make it equal to a new instance of the "GMapTypeControl" class.
  • Add a new control, and pass in "c".

If you refresh your browser, you'll see that the user nows has the option to choose his viewing mode. But what if you want to set the default mode? In such instances, you would use "setMapType".

m.setMapType(G_SATELLITE_MAP);

When defining the default mode, you have three choices.

  • G_SATELLITE_MAP
  • G_NORMAL_MAP
  • G_HYBRID_MAP

You're Finished!

That wasn't too hard, was it? There are a few specific class names that you'll need to memorize, or jot down for later reference. But other than that, it's strikingly simple to implement such an advanced map into your websites.

For you template designers, why not implement this into one of the themes that you sell on ThemeForest?

A few days ago, we posted a tutorial that shows you how to combine many APIs - including Google maps. But many of you didn't know enough to get started. Hopefully, this will help. After you've wrapped your head around this API, why not save yourself some headaches and enlist the help of a PHP class called Phoogle? I think it's best to learn the right way first, but now that you have...cut some corners! See you next week.

Additional Resource

  • Create A Mashup By Combine 3 APIs

    How to Create a Mashup By Combining 3 Different APIs

    This tutorial will show you how to create a mashup of three different APIs including integration with Google Maps.

    Visit Article

    • Subscribe to the RSS Feed and the Video Feed for more daily web development tuts and articles.


Related Posts
  • Web Design
    HTML & CSS
    How to Add Branded Branch Locations to Google MapsMap thumb
    In this tutorial we'll walk through the process of creating a branded Google map for an imaginary client.Read More…
  • Web Design
    HTML/CSS
    Linking Up the Google Maps and Flickr APIsGoogle map flickr retina
    Imagine you've made the beautiful map a client requested; adding all sorts of interesting markers, pop-ups, custom overlays and photos.  But then the client mentions they want to be able to add their own photos without either troubling you, or doing any coding themselves. This is where the Flickr API comes in very handy.Read More…
  • Web Design
    HTML/CSS
    The Google Maps API and Custom OverlaysGoogle map overlay retina
    In our previous tutorial we looked at how you can add markers and customize the colors and menus of a Google map using the service's API. This tutorial takes things a step further, explaining how you can create your own custom map and overlay it onto a Google map (such as my 1896 map of Portsmouth).Read More…
  • Code
    Android SDK
    Android SDK: Working with Google Maps - Displaying Places of InterestAndroid map preview retina
    With Google Maps in your Android apps, you can provide users with localization functions, such as geographical information. Throughout this series we have been building an Android app in which the Google Maps Android API v2 combines with the Google Places API. So far we have displayed a map, in which the user can see their current location, and we have submitted a Google Places query to return data about nearby places of interest. This required setting up API access for both services. In the final part of the series, we will parse the Google Places JSON data and use it to show the user nearby places of interest. We will also make the app update the markers when the user location changes. This is the last of four parts in a tutorial series on Using Google Maps and Google Places in Android apps: Working with Google Maps - Application Setup Working with Google Maps - Map Setup Working with Google Maps - Places Integration Working with Google Maps - Displaying Nearby Places This is a snapshot of the final app. 1. Process the Place Data Step 1 You will need to add the following import statements to your Activity class for this tutorial: [java] import org.json.JSONArray; import org.json.JSONException; import org.json.JSONObject; import android.util.Log; [/java] In the last tutorial we created an inner AsyncTask class to handle fetching the data from Google Places in the background. We added the doInBackground method to request and retrieve the data. Now we can implement the onPostExecute method to parse the JSON string returned from doInBackground, inside your AsyncTask class, after the doInBackground method: [java] protected void onPostExecute(String result) { //parse place data returned from Google Places } [/java] Step 2 Back in the second part of this series, we created a Marker object to indicate the user's last recorded location on the map. We are also going to use Markers to show the nearby places of interest. We will use an array to store these Markers. At the top of your Activity class declaration, add the following instance variable: [java] private Marker[] placeMarkers; [/java] By default, the Google Places API returns a maximum of 20 places, so let's define this as a constant too: [java] private final int MAX_PLACES = 20; [/java] When we create the Markers for each place, we will use MarkerOptions objects to configure the Marker details. Create another array instance variable for these: [java] private MarkerOptions[] places; [/java] Now let's instantiate the array. In your Activity onCreate method, after the line in which we set the map type, create an array of the maximum required size: [java] placeMarkers = new Marker[MAX_PLACES]; [/java] Now let's turn to the onPostExecute method we created. First, loop through the Marker array, removing any existing Markers. This method will execute multiple times as the user changes location: [java] if(placeMarkers!=null){ for(int pm=0; pm<placeMarkers.length; pm++){ if(placeMarkers[pm]!=null) placeMarkers[pm].remove(); } } [/java] When the app code first executes, new Markers will be created. However, when the user changes location, these methods will execute again to update the places displayed. For this reason the first thing we must do is remove any existing Markers from the map to prepare for creating a new batch. Step 3 We will be using Java JSON resources to process the retrieved place data. Since these classes throw certain exceptions, we need to build in a level of error handling throughout this section. Start by adding try and catch blocks: [java] try { //parse JSON } catch (Exception e) { e.printStackTrace(); } [/java] Inside the try block, create a new JSONObject and pass it to the result JSON string returned from doInBackground: [java] JSONObject resultObject = new JSONObject(result); [/java] If you look at the Place Search page on the Google Places API documentation, you can see a sample of what the query actually returns in JSON. You will see that the places are contained within an array named "results". Let's first retrieve that array from the returned JSON object: [java] JSONArray placesArray = resultObject.getJSONArray("results"); [/java] You should refer to the sample JSON result as we complete each section of this process - keep the page open in a browser while you complete the remainder of the tutorial. Next let's instantiate the MarkerOptions array we created with the length of the returned "results" array: [java] places = new MarkerOptions[placesArray.length()]; [/java] This should give us a MarkerOptions object for each place returned. Add a loop to iterate through the array of places: [java] //loop through places for (int p=0; p<placesArray.length(); p++) { //parse each place } [/java] Step 4 Now we can parse the data for each place returned. Inside the for loop, we will build details to pass to the MarkerOptions object for the current place. This will include latitude and longitude, place name, type and vicinity, which is an excerpt of the address data for the place. We will retrieve all of this data from the Google Places JSON, passing it to the Marker for the place via its MarkerOptions object. If any of the values are missing in the returned JSON feed, we will simply not display a Marker for that place, in case of Exceptions. To keep track of this, add a boolean flag: [java] boolean missingValue=false; [/java] Now add local variables for each aspect of the place we need to retrieve and pass to the Marker: [java] LatLng placeLL=null; String placeName=""; String vicinity=""; int currIcon = otherIcon; [/java] We create and initialize a LatLng object for the latitude and longitude, strings for the place name and vicinity and initially set the icon to use the default icon drawable we created. Now we need another try block, so that we can detect whether any values are in fact missing: [java] try{ //attempt to retrieve place data values } catch(JSONException jse){ missingValue=true; jse.printStackTrace(); } [/java] We set the missing value flag to true for checking later. Inside this try block, we can now attempt to retrieve the required values from the place data. Start by initializing the boolean flag to false, assuming that there are no missing values until we discover otherwise: [java] missingValue=false; [/java] Now get the current object from the place array: [java] JSONObject placeObject = placesArray.getJSONObject(p); [/java] If you look back at the sample Place Search data, you will see that each place section includes a "geometry" section which in turn contains a "location" section. This is where the latitude and longitude data for the place is, so retrieve it now: [java] JSONObject loc = placeObject.getJSONObject("geometry").getJSONObject("location"); [/java] Attempt to read the latitude and longitude data from this, referring to the "lat" and "lng" values in the JSON: [java] placeLL = new LatLng( Double.valueOf(loc.getString("lat")), Double.valueOf(loc.getString("lng"))); [/java] Next get the "types" array you can see in the JSON sample: [java] JSONArray types = placeObject.getJSONArray("types"); [/java] [tip] Tip: We know this is an array as it appears in the JSON feed surrounded by the "[" and "]" characters. We treat any other nested sections as JSON objects rather than arrays. [/tip] Loop through the type array: [java] for(int t=0; t<types.length(); t++){ //what type is it } [/java] Get the type string: [java] String thisType=types.get(t).toString(); [/java] We are going to use particular icons for certain place types (food, bar and store) so add a conditional: [java] if(thisType.contains("food")){ currIcon = foodIcon; break; } else if(thisType.contains("bar")){ currIcon = drinkIcon; break; } else if(thisType.contains("store")){ currIcon = shopIcon; break; } [/java] The type list for a place may actually contain more than one of these places, but for convenience we will simply use the first one encountered. If the list of types for a place does not contain any of these, we will leave it displaying the default icon. Remember that we specified these types in the Place Search URL query string last time: [text] food|bar|store|museum|art_gallery [/text] This means that the only place types using the default icon will be museums or art galleries, as these are the only other types we asked for. After the loop through the type array, retrieve the vicinity data: [java] vicinity = placeObject.getString("vicinity"); [/java] Finally, retrieve the place name: [java] placeName = placeObject.getString("name"); [/java] Step 5 After the catch block in which you set the missingValue flag to true, check that value and set the place MarkerOptions object to null, so that we don't attempt to instantiate any Marker objects with missing data: [java] if(missingValue) places[p]=null; [/java] Otherwise, we can create a MarkerOptions object at this position in the array: [java] else places[p]=new MarkerOptions() .position(placeLL) .title(placeName) .icon(BitmapDescriptorFactory.fromResource(currIcon)) .snippet(vicinity); [/java] Step 6 Now, at the end of onPostExecute after the outer try and catch blocks, loop through the array of MarkerOptions, instantiating a Marker for each, adding it to the map and storing a reference to it in the array we created: [java] if(places!=null && placeMarkers!=null){ for(int p=0; p<places.length && p<placeMarkers.length; p++){ //will be null if a value was missing if(places[p]!=null) placeMarkers[p]=theMap.addMarker(places[p]); } } [/java] Storing a reference to the Marker allows us to easily remove it when the places are updated, as we implemented at the beginning of the onPostExecute method. Notice that we include two conditional tests each time this loop iterates, in case the Place Search did not return the full 20 places. We also check in case the MarkerOptions is null, indicating that a value was missing. Step 7 Finally, we can instantiate and execute our AsyncTask class. In your updatePlaces method, after the existing code in which we built the search query string, start this background processing to fetch the place data using that string: [java] new GetPlaces().execute(placesSearchStr); [/java] You can run your app now to see it in action. It should display your last recorded location together with nearby places of interest. The colors you see on the Markers will depend on the places returned. Here is the app displaying a user location in Glasgow city center, UK: Perhaps unsurprisingly a lot of the places listed in Glasgow are bars. When the user taps a Marker, they will see the place name and snippet info: 2. Update With User Location Changes Step 1 The app as it stands will execute once when it is launched. Let's build in the functionality required to make it update to reflect changes in the user location, refreshing the nearby place Markers at the same time. Alter the opening line of the Activity class declaration to make it implement the LocationListener interface so that we can detect changes in the user location: [java] public class MyMapActivity extends Activity implements LocationListener { [/java] A Location Listener can respond to various changes, each of which uses a dedicated method. Inside the Activity class, implement these methods: [java] @Override public void onLocationChanged(Location location) { Log.v("MyMapActivity", "location changed"); updatePlaces(); } @Override public void onProviderDisabled(String provider){ Log.v("MyMapActivity", "provider disabled"); } @Override public void onProviderEnabled(String provider) { Log.v("MyMapActivity", "provider enabled"); } @Override public void onStatusChanged(String provider, int status, Bundle extras) { Log.v("MyMapActivity", "status changed"); } [/java] The only one we are really interested in is the first, which indicates that the location has changed. In this case we call the updatePlaces method again. Otherwise we simply write out a Log message. At the end of the updatePlaces method, add a request for the app to receive location updates: [java] locMan.requestLocationUpdates(LocationManager.NETWORK_PROVIDER, 30000, 100, this); [/java] We use the Location Manager we created earlier in the series, requesting updates using the network provider, at delays of 30 seconds (indicated in milliseconds), with a minimum location change of 100 meters and the Activity class itself to receive the updates. You can, of course, alter some of the parameters to suit your own needs. [tip] Tip: Although the requestLocationUpdates method specifies a minimum time and distance for updates, in reality it can cause the onLocationChanged method to execute much more often, which has serious performance implications. In any apps you plan on releasing to users, you should therefore limit the frequency at which your code responds to these location updates. The alternative requestSingleUpdate method used on a timed basis may be worth considering. [/tip] Step 2 Last but not least, we need to take care of what happens when the app pauses and resumes. Override the two methods as follows: [java] @Override protected void onResume() { super.onResume(); if(theMap!=null){ locMan.requestLocationUpdates(LocationManager.NETWORK_PROVIDER, 30000, 100, this); } } @Override protected void onPause() { super.onPause(); if(theMap!=null){ locMan.removeUpdates(this); } } [/java] We check for the GoogleMap object before attempting any processing, as in onCreate. If the app is pausing, we stop it from requesting location updates. If the app is resuming, we start requesting the updates again. [tip] Tip: We've used the LocationManager.NETWORK_PROVIDER a few times in this series. If you are exploring localization functionality in your apps, check out the alternative getBestProvider method with which you can specify criteria for Android to choose a provider based on such factors as accuracy and speed. [/tip] Before We Finish That pretty much completes the app! However, there are many aspects of the Google Maps Android API v2 that we have not even touched on. Once you have your app running you can experiment with features such as rotation and tilting. The updated maps service displays indoor and 3D maps in certain places. The following image shows the 3D facility with the app if the user location was in Venice, Italy: This has the map type set to normal - here is another view of Venice with the hybrid map type set: Conclusion In this tutorial series we have worked through the process of integrating both Google Maps and Google Places APIs in a single Android app. We handled API key access, setting up the development environment, workspace and application to use Google Play Services. We utilized location data, showing the user location together with nearby places of interest, and displaying the data with custom UI elements. Although what we have covered in this series is fairly extensive, it really is only the beginning when it comes to building localization features into Android apps. With the release of Version 2 of the Maps API, Android apps are set to take such functions to the next level.Read More…
  • Code
    Android SDK
    Android SDK: Working with Google Maps - Map SetupAndroid google maps v2 preview@2x
    With the Google Maps Android API, you can build apps with localization features. In this series, we are creating an Android app in which the user's location is presented on a map, as are nearby places of interest. In this part we will use the GoogleMap class to show the user location and also to control how the map presents itself to the user. We will also create custom map markers!Read More…
  • Code
    Mobile Web Apps
    Creating a Mobile Event Calendar With DHTMLXMobile calendar preview@2x
    This tutorial describes how to build an HTML5-based mobile calendar to track conferences and events that run on iOS and Android phones using a mobile version of dhtmlxScheduler (open source, GPL). At the end, users will be able to add and edit events, select the conference location on Google Maps, and see the events in day, month, or list views.Read More…