Google Maps API Premier Developer's Guide

The Google Maps API lets you add easy-to-use interactive maps to your public website, enhancing your customers' experience by helping them find exactly what they need from your organization. That's why it's the most popular mapping API in the world. When Google Maps plays an important role on your public website, or is incorporated in an internal application for your employees, organizations need an enterprise-class application that handles high volumes and provides necessary support.

Why Google Maps API Premier?

Google Maps API Premier provides Enterprise-ready application support for your mapping application needs. Google Maps API Premier uses the same code base as the standard Google Maps API, but provides the following additional features and benefits:

• A robust Service Level Agreement (SLA)
• Customer support
• Increased geocoding limits
• Commercial-grade terms and conditions
• Intranet application support within the enterprise
• Access to the API via a secure https connection

Google Maps API Premier requires registration of your website to access these additional features. For more information, contact us.

This documentation discusses use cases and coding issues particular to the Google Maps API Premier product. For full documentation on all common code, use this guide in consultation with the existing Google Maps API Documentation.

Specifying a Client ID

To access the special features of Google Maps API Premier, you must provide a client ID when accessing any of the Premier API libraries or services. When registering for Google Maps API Premier, you will receive this client ID from Google Enterprise Support. All client IDs begin with a gme- prefix.

Your client ID may be tied to one or more website domains. For existing customers, any domain which you previously tied to your Premier account through issuance of an API key will have been automatically added to your account. If you wish to obtain a list of your currently enabled domains, or enable additional domains for your client ID, please contact Google Enterprise Support. There is no limit to the number of domains that can be enabled for your client ID.

Note: this client ID is not a key. It will only work from domains which you authorize so you don't need to worry about keeping it secret. Users of Google Maps API Premier no longer need to register or provide an API key when using the Maps API or one of its services.

Tracking Usage with the sensor Parameter

Use of the Google Maps API(s) now requires that you indicate whether your application is using a sensor (such as a GPS locator) to determine the user's location in any Maps API library or service requests. This is especially important for mobile devices. If your Google Maps API application uses any form of sensor to determine the location of the device accessing your application, you must declare this with a sensor parameter value of true.

Note that even if your application does not use a location sensor, you still must set the sensor parameter (in this case to false).

URL Authentication

Requests to certain Maps API Premier services now require digital signatures using a cryptographic key we provide to you for that purpose. The signing process combines a URL and a private key together using an encryption algorithm, creating a unique signature. This unique signature allows our services to verify that any site generating requests that use your Maps API Premier client ID are authorized to do so. The signature is also unique per URL, ensuring that requests that use your client ID cannot be modified without requiring a new signature to be generated.

URL signing serves both to authenticate you to our services as well as accurately track your usage. We encourage you to begin converting all of your applications to incorporate signing of URL requests as we roll this feature out to additional services.

Currently, only the following Premier services require URL signatures:

• The Static Maps API V2 service

In the future, more services will implement URL signing as we launch new or upgrade existing services.

The URL Signing Process

Signing a URL involves generating a signature using a private key shared between you and Google, which you attach to any HTTP (or HTTPS) requests. See How Do I Get My Private Key? below. You generate this signature for a URL using the private key, which creates a hash that is unique to that URL and the private key. If the URL differs in any way from that used to generate the signature, the service will reject the request as invalid.

Note: attempting to access a service with an invalid signature will result in a HTTP 403 (Forbidden) error. As you convert your applications to use URL signing, make sure to test your signatures to ensure they initiate a valid request. You should first test whether the original URL is valid (See Building a Valid URL below) as well as test whether you generate the correct signatures (See Generating Valid Signatures below).

How Do I Get My Private Key?

Your cryptographic URL-signing key will be sent to the technical contact for existing customers, and issued with new client IDs for new customers. This private key is unique to your client ID. For that reason, please keep your key secure. This key — though used to generate the signature — should not be passed within any requests, stored on any websites, or posted to any public forum. Anyone obtaining this key "in the clear" could spoof requests using your identity.

Note that this cryptographic key is not the same as the (freely available) Maps API key. The Maps API key is solely for identification purposes and is not used by Premier customers; your URL-signing key serves to both identify and authenticate your requests.

Building a Valid URL

Before you can sign your request, you first need to ensure that your URL is valid. You may think that a "valid" URL is self-evident, but that's not quite the case. A URL entered within an address bar in a browser, for example, may contain special characters (e.g. "上海+中國"); the browser needs to internally translate those characters into a different encoding before transmission. By the same token, any code that generates or accepts UTF-8 input might treat URLs with UTF-8 characters as "valid", but would also need to translate those characters before sending them out to a web server. This process is called URL-encoding.

We need to translate special characters because all URLs need to conform to the syntax specified by the W3 Uniform Resource Identifier specification. In effect, this means that URLs must contain only a special subset of ASCII characters: the familiar alphanumeric symbols, and some reserved characters for use as control characters within URLs. The table below summarizes these characters:

When building a valid URL, you must ensure that it contains only those characters shown above. Conforming a URL to use this set of characters generally leads to two issues, one of omission and one of substitution:

• Characters that you wish to handle exist outside of the above set. For example, characters in foreign languages such as 上海+中國 need to be encoded using the above characters. By popular convention, spaces (which are not allowed within URLs) are often represented using the plus '+' character as well.
• Characters exist within the above set as reserved characters, but need to be used literally. For example, ? is used within URLs to indicate the beginning of the query string; if you wish to use the string "? and the Mysterions," you'd need to encode the '?' character.

All characters to be URL-encoded are encoded using a '%' character and a two-character hex value corresponding to their UTF-8 character. For example, 上海+中國 in UTF-8 would be URL-encoded as %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. The string ? and the Mysterians would be URL-encoded as %3F+and+the+Mysterians.

Converting a URL that you receive from user input is sometimes tricky. For example, a user may enter an address as "5th&Main St." Generally, you should construct your URL from its parts, treating any user input as literal characters.

Generating Valid Signatures

To aid debugging, make sure that your URLs are already valid before you sign them! Doing so allows you to focus on correcting invalid signatures if you discover errors when signing your URLs. We recommend that you may use the free services to test your URLs before adding the client parameter and signing the URL. See Building Valid URLs for more information.

The following steps outline the process you should use to sign a valid URL:

1. Construct your URL, making sure to include your client and sensor parameters. Note that any non-standard characters will need to be URL-encoded:

     http://maps.google.com/maps/api/staticmap?center=%E4%B8%8A%E6%B5%B7+%E4%B8%AD%E5%9C%8B&client=clientID&sensor=true_or_false
     

   Note: all Google services require UTF-8 character encoding (which implicitly includes ASCII). Make sure that if your applications operate using other character sets, that they construct URLs using UTF-8 and properly URL-encode them beforehand.

2. Strip off the domain portion of the request, leaving only the path and the query:

     /maps/api/staticmap?center=%E4%B8%8A%E6%B5%B7+%E4%B8%AD%E5%9C%8B&client=clientID&sensor=true_or_false
     

3. Retrieve your private key, which is encoded in a modified Base64 for URLs *, and sign the URL above using the HMAC-SHA1 algorithm. You may need to decode this key into its original binary format. Note that in most cryptographic libraries, the resulting signature will be in binary format.

4. Encode the resulting binary signature using the modified Base64 for URLs * to convert this signature into something that can be passed within a URL.

5. Attach this signature to the URL within a signature parameter:

     http://maps.google.com/maps/api/staticmap?center=%E4%B8%8A%E6%B5%B7+%E4%B8%AD%E5%9C%8B&client=clientID&sensor=true_or_false&signature=base64signature  
     

* Note: Modified Base64 for URLs replaces the '+' and '/' characters of standard Base64 with '-' and '_' respectively, so that these Base64 signatures no longer need to be URL-encoded.

Signature Examples

The following sections show ways to implement URL signing using server-side code. For simplicity, many of these samples have hard-coded URLs and private keys.

For testing purposes, you can test the following URL and private key to see if it generates the correct signature. Note that this private key is purely for testing purposes and will not be validated by any Google services.

URL: http://maps.google.com/maps/api/geocode/json?address=New+York&sensor=false
Private Key: vNIXE0xscrmjlyV-12Nj_BvUPaw=
URL Portion to Sign: /maps/api/geocode/json?address=New+York&sensor=false
Signature: Pu5wB23-wbDA-o4YFOsgtbAFjk4=
Full Signed URL: http://maps.google.com/maps/api/geocode/json?address=New+York&sensor=false&signature=Pu5wB23-wbDA-o4YFOsgtbAFjk4=

Example: Signing a URL in Python

The example below uses standard Python libraries to sign a URL and output a proper URL request.

 Show/Hide Code

#!/usr/bin/python
# coding: utf8

import sys
import hashlib
import urllib
import hmac
import base64
import urlparse

print("")
print("URL Signer 1.0")
print("")

# Convert the URL string to a URL, which we can parse
# using the urlparse() function into path and query
# Note that this URL should already be URL-encoded
url = urlparse.urlparse("YOUR_URL_TO_SIGN")

privateKey = "YOUR_PRIVATE_KEY"

# We only need to sign the path+query part of the string
urlToSign = url.path + "?" + url.query

# Decode the private key into its binary format
decodedKey = base64.b64decode(privateKey)

# Create a signature using the private key and the URL-encoded
# string using HMAC SHA1. This signature will be binary.
signature = hmac.new(decodedKey, urlToSign, hashlib.sha1)

# Encode the binary signature into base64 for use within a URL
encodedSignature = base64.urlsafe_b64encode(signature.digest())
originalUrl = url.scheme + "://" + url.netloc + url.path + "?" + url.query
print("Full URL: " + originalUrl + "&signature=" + encodedSignature)

Download the code from gmaps-samples

Example: Signing a URL in Java

The example below uses this public domain Base64 encoding class to sign a URL and output a proper URL request. (Be sure to include that class in your CLASSPATH when compiling the Java code shown below.)

 Show/Hide Code

public class UrlSigner {

  // Note: Generally, you should store your private key someplace safe
  // and read them into your code

  private static String keyString = "YOUR_PRIVATE_KEY";
  
  // The URL shown in these examples must be already
  // URL-encoded. In practice, you will likely have code
  // which assembles your URL from user or web service input
  // and plugs those values into its parameters.
  private static String urlString = "YOUR_URL_TO_SIGN";

  // This variable stores the binary key, which is computed from the string (Base64) key
  private static byte[] key;
  
  public static void main(String[] args) throws IOException,
    InvalidKeyException, NoSuchAlgorithmException, URISyntaxException {
    
    // Convert the string to a URL so we can parse it
    URL url = new URL(urlString);
    
    UrlSigner signer = new UrlSigner(keyString);
    String request = signer.signRequest(url.getPath(),url.getQuery());
    
    System.out.println("Signed URL :" + url.getProtocol() + "://" + url.getHost() + request);
  }
  
  public UrlSigner(String keyString) throws IOException {
    // Convert the key from 'web safe' base 64 to binary
    keyString = keyString.replace('-', '+');
    keyString = keyString.replace('_', '/');
    System.out.println("Key: " + keyString);
    this.key = Base64.decode(keyString);
  }

  public String signRequest(String path, String query) throws NoSuchAlgorithmException,
    InvalidKeyException, UnsupportedEncodingException, URISyntaxException {
    
    // Retrieve the proper URL components to sign
    String resource = path + '?' + query;
    
    // Get an HMAC-SHA1 signing key from the raw key bytes
    SecretKeySpec sha1Key = new SecretKeySpec(key, "HmacSHA1");

    // Get an HMAC-SHA1 Mac instance and initialize it with the HMAC-SHA1 key
    Mac mac = Mac.getInstance("HmacSHA1");
    mac.init(sha1Key);

    // compute the binary signature for the request
    byte[] sigBytes = mac.doFinal(resource.getBytes());

    // base 64 encode the binary signature
    String signature = Base64.encodeBytes(sigBytes);
    
    // convert the signature to 'web safe' base 64
    signature = signature.replace('+', '-');
    signature = signature.replace('/', '_');
    
    return resource + "&signature=" + signature;
  }
}

Download the code from gmaps-samples

Example: Signing a URL in C#

The example below uses the default System.Security.Cryptography library to sign a URL request and output a proper URL request. Note that we need to convert the default Base64 encoding to implement an URL-safe version.

 Show/Hide Code

using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using System.Text.RegularExpressions;
using System.Web;

namespace SignUrl {

  public struct GoogleSignedUrl {

    public static string Sign(string url, string keyString) {
      ASCIIEncoding encoding = new ASCIIEncoding();

      // converting key to bytes will throw an exception, need to replace '-' and '_' characters first.
      string usablePrivateKey = keyString.Replace("-", "+").Replace("_", "/");
      byte[] privateKeyBytes = Convert.FromBase64String(usablePrivateKey);

      Uri uri = new Uri(url);
      byte[] encodedPathAndQueryBytes = encoding.GetBytes(uri.LocalPath + uri.Query);

      // compute the hash
      HMACSHA1 algorithm = new HMACSHA1(privateKeyBytes);
      byte[] hash = algorithm.ComputeHash(encodedPathAndQueryBytes);

      // convert the bytes to string and make url-safe by replacing '+' and '/' characters
      string signature = Convert.ToBase64String(hash).Replace("+", "-").Replace("/", "_");
            
      // Add the signature to the existing URI.
      return url +"&signature=" + signature; 
    }
  }

  class Program {

    static void Main() {

      // Note: Generally, you should store your private key someplace safe
      // and read them into your code

      const string keyString = "YOUR_PRIVATE_KEY";

      // The URL shown here is a static URL which should be already
      // URL-encoded. In practice, you will likely have code
      // which assembles your URL from user or web service input
      // and plugs those values into its parameters.
      const  string urlString = "YOUR_URL_TO_SIGN";

      Console.WriteLine(GoogleSignedUrl.Sign(urlString,keyString));
    }
  }
}

Download the code from gmaps-samples

Accessing and Loading the API

Loading an API library or service as a Premier application requires specification of the Client ID within a client parameter. How you specify this value depends on the library or service you utilize.

• Loading the Google Maps JavaScript API
• Loading the Google Maps API for Flash
• Loading the Google Earth API

Loading the Google Maps JavaScript API

• Using the client Parameter
• Using the Common Loader

Using the client Parameter

To load the Google Maps JavaScript API using your Google Maps API Premier client ID, append an additional client parameter onto the URL used to retrieve the JavaScript library:

<script src="http://maps.google.com/maps?file=api&v=2&client=gme-yourclientid&sensor=false" type="text/javascript"></script>

Note that you do not need to provide an API key in this URL, though you do need to provide a sensor parameter.

Google Maps API Premier customers can also access the Google Maps JavaScript API over https. In order to use the Google Maps JavaScript API over https your client ID must first be enabled for https access by Google Enterprise Support. If your client has not been enabled for https, requests will instead be redirected to HTTP.

To load the Google Maps JavaScript API over https, you use the HTTPS protocol and load the API from the following URL:

<script src="https://maps-api-ssl.google.com/maps?file=api&v=2&client=gme-yourclientid&sensor=false"
type="text/javascript"></script>

Using the Common Loader

The Google Maps JavaScript API is now fully integrated with the Google AJAX APIs as documented at http://code.google.com/apis/maps/documentation/#AJAX_Loader.

It is not necessary to provide an API key when loading the common loader if you wish to load the Google Maps JavaScript API with your Google Maps API Premier client ID:

<script type="text/javascript" src="http://www.google.com/jsapi"></script>

When loading the Google Maps JavaScript API using the common loader, provide your client ID within the other_params option:

google.load("maps","2", {"other_params":"client=gme-yourclientid&sensor=false"}); 

Google Maps API Premier customers can also load the Google Maps JavaScript API over https. In order to use the Google Maps JavaScript API over https your client ID must first be enabled for HTTPS access by Google Enterprise Support.

To load the Google Maps JavaScript API over https using the Google AJAX API Loader, first load the common loader over https:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

Once loaded, you can then load the Google Maps JavaScript API using google.load() as shown above.

As with requests made for the Google Maps JavaScript API over https, loading the Maps API using the Common Loader with a client ID that has not been enabled for https will be redirected to HTTP.

Loading the Google Maps API for Flash

Your Google Maps API Premier client ID also allows you to access the Google Maps API for Flash as an Enterprise application. Full documentation for the Google Maps API for Flash is available at http://code.google.com/apis/maps/documentation/flash/. As with the JavaScript API, you will need to pass client and sensor parameters when accessing the API, though you will not need an API key.

Note: The Google Maps for Flash API removed the need to provide API keys for Premier customers starting with version 1.8b of the Flash SDK. Be sure you compile your application using that version or later to take advantage of keyless functionality. Existing applications will need to be re-compiled with this version to enable keyless support.

There are three ways to supply your Google Maps API Premier client ID when accessing the Google Maps API for Flash. Whichever you choose, we recommend that you supply both your client ID and the sensor parameter in the same manner:

1. Supply your client ID and sensor parameter as attributes of the UI container object declared in your MXML:

   <maps:Map xmlns:maps="com.google.maps.*" id="map"
   mapevent_mapready="onMapReady(event)" width="100%" height="100%" 
   sensor="false" client="gme-yourclientid"/>
   

   This method is preferred if you are developing your application using FlexBuilder or the Flex framework.

2. Supply your client ID and sensor parameter as attributes of the object and embed tags used to add your Flash application to a web page:

   <div id="map_canvas" name="map_canvas">
     <object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
         codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,29,0"
         width="800px"
         height="600px">
       <param name="movie" value="helloworld.swf">
       <param name="quality" value="high">
       <param name="flashVars" value="client=gme-yourclientid&sensor=false">
       <embed width="800px"
           height="600px"
           src="helloworld.swf"
           quality="high"
           flashVars="client=gme-yourclientid&sensor=false"
           pluginspage="http://www.macromedia.com/go/getflashplayer"
           type="application/x-shockwave-flash">
       </embed> 
     </object> 
   </div>
   

3. Supply your client ID and sensor parameter as properties of your Map object directly within ActionScript code:

     var map:Map = new Map();
     map.sensor = false;
     map.client = "gme-yourclientid";
   

   This method is necessary if you are developing your application within Flash CS3.

You can now load your Google Maps API for Flash application securely over https. To enable this functionality, your client ID must first be enabled for HTTPS access by Google Enterprise Support. Your application will also need to be built against version 1.18 or later of the Google Maps API for Flash.

To load the Google Maps API for Flash over https, use the HTTPS protocol to load your application and pass a ssl property set to true to instruct the application to load the API over HTTPS. As with the client and sensor parameters, this ssl parameter may be set in either the MXML file, within the flashVars elements of your HTML, or as a direct property of the Map object within your ActionScript code.

The MXML specification below indicates that this application should load the API over https.

<maps:Map xmlns:maps="com.google.maps.*" id="map"
mapevent_mapready="onMapReady(event)" width="100%" height="100%" 
sensor="false" ssl="true" client="gme-yourclientid"/>

Note: your containing SWF application must also be loaded over HTTPS in order to properly load the API over HTTPS.

Loading the Google Earth API

The Google Earth API gives you control of a three dimensional globe in your web pages and applications. Documentation is available at http://code.google.com/apis/earth/documentation.

Authenticating with a Client ID

The Earth API must be loaded with the Google AJAX API Loader. Do not include an API key when referencing the jsapi file; you'll supply your client ID in the next step.

<script src="http://www.google.com/jsapi"></script>

Your client ID is passed to the google.load() method within the other_params property, as follows:

google.load("earth","1", {"other_params":"client=gme-yourclientid&sensor=false"});

The client and sensor parameters are required.

More information about loading and getting started with the Earth API is available from the Google Earth API Developer's Guide.

HTTPS Connections

To access the Earth API using a secure https connection, update the protocol from http to https in the src value:

<script src="https://www.google.com/jsapi"></script>

To load the Earth API over https, your client ID must first be enabled for https access by Google Enterprise Support. Secure https connections are only available when authenticating with a client ID.

Using Maps API Services

Your Google Maps API Premier client ID not only allows you to access the JavaScript API with Enterprise support, but also any existing Google Maps API services. Using these services with a Premier license allows you increased access and support.

Static Maps API

The Google Static Maps API allows you to construct and retrieve map images using parameters passed through its URL service. Full documentation of the Google Static Maps V2 API is available at http://code.google.com/apis/maps/documentation/staticmaps/. Static Maps API requests using a Premier client ID have higher query limits.

The Google Static Maps V1 API at http://maps.google.com/staticmap has been deprecated. We encourage you to move your applications to the V2 API. Applications using the V1 API will continue to be supported in accordance with the Maps API deprecation policy.

To embed a map image in a webpage using your Google Maps API Premier client ID, append a client parameter containing your client ID to the Static Map URL, also passing a sensor parameter value.

http://maps.google.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&client=gme-yourclientid&sensor=false 

Note that you do not need to pass an API key.

Google Maps API Premier customers can also make requests to the Static Maps API over https. In order to use the Static Maps API over https your client ID must first be enabled for HTTPS access by Google Enterprise Support.

To embed a map image into a page retrieved over a secure https connection, use the alternative hostname in your request URL as shown below:

https://maps-api-ssl.google.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=400x400&client=gme-yourclientid&sensor=false

Note: Static Maps API Requests over https using a client ID that has not been enabled for https will be rejected with a Status 400 "Bad Request" error.

Geocoding Service

The Google Maps Geocoding service allows you to request latitude and longitude information for address queries. Full documentation of the Google HTTP Geocoder is available at http://code.google.com/apis/maps/documentation/services.html#Geocoding_Direct.

To request a geocode from the Google HTTP Geocoder using your Google Maps API Premier client ID, append a client parameter containing your client ID to the Geocoder URL.

http://maps.google.com/maps/geo?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&output=xml&client=gme-yourclientid&sensor=false

Note that you do not need to provide an API key in this URL, though you do need to provide a sensor parameter.

Google Maps API Premier customers can also make requests to the Geocoding Service over https. In order to use the Geocoding Service over https your client ID must first be enabled for HTTPS access by Google Enterprise Support.

To request a geocode using the Google HTTP Geocoder over https, use the alternative hostname in your request URL as shown below:

https://maps-api-ssl.google.com/maps/geo?q=1600+Amphitheatre+Parkway,+Mountain+View,+CA&output=xml&client=gme-yourclientid&sensor=false

Requests made to the Maps API Geocoding service over https using a client ID that has not been enabled for https will return a 610 (G_GEO_BAD_KEY) geocoder response. Requests made in excess of your daily and instantaneous throughput limits may return a 620 (G_GEO_TOO_MANY_QUERIES).

Determining Application Usage

Google Maps API Premier enables customers to determine and analyze the activity on your API application based on client ID. However, in some cases you may wish to provide a finer breakdown of usage across different applications using the same client ID. In those cases, you may provide an optional channel parameter when accessing any of the Premier API libraries or services. By specifying different channel values for different aspects of your application, you can determine precisely how your application is used.

This channel is a unique string which you define and will be logged when accessing the Google Maps API Premier services. Google will provide you usage statistics for your client ID broken down by your defined channels in your Enterprise support portal.

For example, your externally facing website may access the API using a channel set to customer while your internal marketing department may instead have a channel set to mkting. Your reports will break down usage by those channel values.

The channel parameter must be an ASCII alphanumeric string. Additionally, the period (.) and hyphen (-) values are allowed. Note: The channel value must be a static value assigned per application instance, and must not be generated dynamically. You may not use channel values to track individual users, for example.

The channel parameter is provided in the same manner as the client and sensor parameters within each Maps API or service. For example, if loading the Maps JavaScript API from http://maps.google.com or http://maps-api-ssl.google.com, append a channel parameter to the src URL of your script tag:

<script src="http://maps.google.com/maps?file=api&v=2&client=gme-yourclientid&sensor=false&channel=yourchannel" type="text/javascript"></script>

Support

Google Maps API Premier comes with dedicated Enterprise-level support. Once you obtain a Premier license, you'll receive contact information from a Google Maps API Enterprise Support representative.