Client Libraries for Google Maps Web Services

The Java, Python and Go client libraries for Google Maps web services enable you to work with Google Maps web services on your server. They wrap the functionality of the following APIs:

In addition to the functionality provided by these APIs, the client libraries make some common tasks a little easier.

  • Automatic Rate Limiting By default, requests are sent at the expected rate limit for each web service. You can provide custom QPS limits with new GeoApiContext().setQueryRateLimit(qps).
  • Retry on Failure The client libraries will automatically retry any request if the API sends a 5xx error. Retries use exponential back-off, which helps in the event of intermittent failures.
  • Easy Authentication The client libraries make it easy to authenticate with your freely available API Key. Maps for Work customers can use their client ID and secret.
  • POJOs The Java libraries return native objects for each of the API responses (the Python libraries return the structure as it is received from the API).
  • Asynchronous or synchronous All requests support synchronous or asynchronous calling style.

Terms and Conditions

The client libraries for Google Maps Services are licensed under the Apache 2.0 License. They are available for download, or contributions, at:

The client libraries are wrappers for the Google Maps web services. The Google Maps web services are governed by the Google Maps APIs Terms of Service.

Requirements

  • A Google Maps API key or Client ID.
  • Java 1.6 or later (Java client library only).
  • Python 2.7 or later (Python client library only).
  • Go 1.x or later (Go client library only).

API Keys and Client IDs

Each Google Maps web service requires an API key or client ID. For a guide on when to use an API key, when to use a client ID, and how to get hold of your API key or client ID, see the documentation for the API you're using. For example, see the guide for the Directions API.

Installation and Source Code (Java)

You can add the library to your project via Maven or Gradle.

Maven

<dependency>
    <groupId>com.google.maps</groupId>
    <artifactId>google-maps-services</artifactId>
    <version>(insert latest version)</version>
</dependency>

Gradle

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.google.maps:google-maps-services:(insert latest version)'
    ...
}

You can find the latest version by searching Maven Central or Gradle, Please.

Source Code

You can access the source code for the Java Client for Google Maps Services at https://github.com/googlemaps/google-maps-services-java/

Usage (Java)

This example uses the Google Maps Geocoding API with an API Key.

// Replace the API key below with a valid API key.
GeoApiContext context = new GeoApiContext().setApiKey("YOUR_API_KEY");
GeocodingResult[] results =  GeocodingApi.geocode(context,
    "1600 Amphitheatre Parkway Mountain View, CA 94043").await();
System.out.println(results[0].formattedAddress);

Below is the same example, using client ID and client secret (digital signature) for authentication. This code assumes you have previously loaded the clientID and clientSecret variables with appropriate values.

For a guide on how to generate the clientSecret (digital signature), see the documentation for the API you're using. For example, see the guide for the Directions API.

GeoApiContext context = new GeoApiContext().setEnterpriseCredentials(clientID, clientSecret);
GeocodingResult[] results =  GeocodingApi.geocode(context,
    "1600 Amphitheatre Parkway Mountain View, CA 94043").await();
System.out.println(results[0].formattedAddress);

Synchronous requests

GeocodingApiRequest req = GeocodingApi.newRequest(context).address("Sydney");

try {
    req.await();
    // Handle successful request.
} catch (Exception e) {
    // Handle error
}

req.awaitIgnoreError(); // No checked exception.

Asynchronous requests

req.setCallback(new PendingResult.Callback<GeocodingResult[]>() {
  @Override
  public void onResult(GeocodingResult[] result) {
    // Handle successful request.
  }

  @Override
  public void onFailure(Throwable e) {
    // Handle error.
  }
});

Installation and Source Code (Python)

$ pip install -U googlemaps

Note that you will need requests 2.4.0 or higher if you want to specify connect/ read timeouts.

Source Code

You can access the source code for the Python Client for Google Maps Services at https://github.com/googlemaps/google-maps-services-python.

Usage (Python)

This example uses the Google Maps Geocoding API and Google Directions API.

# Replace the API key below with a valid API key.
gmaps = googlemaps.Client(key='YOUR_API_KEY')

# Geocoding and address
geocode_result = gmaps.geocode('1600 Amphitheatre Parkway, Mountain View, CA')

# Look up an address with reverse geocoding
reverse_geocode_result = gmaps.reverse_geocode((40.714224, -73.961452))

# Request directions via public transit
now = datetime.now()
directions_result = gmaps.directions("Sydney Town Hall",
                                     "Parramatta, NSW",
                                     mode="transit",
                                     departure_time=now)

Below is the same example, using client ID and client secret (digital signature) for authentication. This code assumes you have previously loaded the client_id and client_secret variables with appropriate values.

For a guide on how to generate the client_secret (digital signature), see the documentation for the API you're using. For example, see the guide for the Directions API.

gmaps = googlemaps.Client(client_id=client_id, client_secret=client_secret)

# Geocoding and address
geocode_result = gmaps.geocode('1600 Amphitheatre Parkway, Mountain View, CA')

# Look up an address with reverse geocoding
reverse_geocode_result = gmaps.reverse_geocode((40.714224, -73.961452))

# Request directions via public transit
now = datetime.now()
directions_result = gmaps.directions("Sydney Town Hall",
                                     "Parramatta, NSW",
                                     mode="transit",
                                     departure_time=now)

Installation and Source Code (Go)

$ go get googlemaps.github.io/maps

Note you will also need github.com/kr/pretty installed to run the examples.

Source Code

You can access the source code for the Go Client for Google Maps Services at https://github.com/googlemaps/google-maps-services-go.

Usage (Go)

This example uses the Google Directions API.

package main

import (
    "log"

    "googlemaps.github.io/maps"
    "github.com/kr/pretty"
    "golang.org/x/net/context"
)

func main() {
    c, err := maps.NewClient(maps.WithAPIKey("YOUR_API_KEY"))
    if err != nil {
        log.Fatalf("fatal error: %s", err)
    }
    r := &maps.DirectionsRequest{
        Origin:      "Sydney",
        Destination: "Perth",
    }
    resp, err := c.Directions(context.Background(), r)
    if err != nil {
        log.Fatalf("fatal error: %s", err)
    }

    pretty.Println(resp)
}

Below is the same example, using client ID and client secret (digital signature) for authentication. This code assumes you have previously loaded the clientID and clientSecret variables with appropriate values.

For a guide on how to generate the clientSecret (digital signature), see the documentation for the API you're using. For example, see the guide for the Directions API.

package main

import (
    "log"

    "googlemaps.github.io/maps"
    "github.com/kr/pretty"
    "golang.org/x/net/context"
)

func main() {
    c, err := maps.NewClient(maps.WithClientIDAndSignature(clientID, clientSecret))
    if err != nil {
        log.Fatalf("fatal error: %s", err)
    }
    r := &maps.DirectionsRequest{
        Origin:      "Sydney",
        Destination: "Perth",
    }
    resp, err := c.Directions(context.Background(), r)
    if err != nil {
        log.Fatalf("fatal error: %s", err)
    }

    pretty.Println(resp)
}

Send feedback about...

This page
Documentation feedback
Google Maps Web Service APIs
Google Maps Web Service APIs
Product feedback