Getting Started

This guide introduces the features in the Google Places API for Android and shows you how to configure your app to use the API.

1. Introduction and concepts
2. API overview
3. Supported versions of Android platform
4. Configure your app
1. Set up Google Play services
2. Add your API key
3. Request an uplift in usage limits
5. Connect to the Places API

Introduction and concepts

The main entry points for the Google Places API for Android are the PlacePicker UI widget, the Autocomplete UI widget, the GeoDataApi, and the PlaceDetectionApi.

Using the Google Places API for Android, you can build location-aware apps that respond contextually to the local businesses and other places near the device. This means that you can build rich apps based on places that mean something to the user, to complement the straightforward geographic-based services offered by the Android location services.

A place is defined as a physical space that has a name. Another way of thinking about a place is that it's anything you can find on a map. Examples include local businesses, points of interest, and geographic locations. In the API, a place is represented by the Place interface. It includes information such as the name of the place and its address, geographical location, place ID, phone number, place type, website URL, and more.

API overview

Help your customers explore where they are and what’s around them:

• Use the built-in place picker UI widget, allowing users to select a place on an interactive map.
• Get the current place, that is, the place where the device is last known to be located. The API returns a list of likely places and an indication of the relative likelihood for each place.
• Make it easy to enter place names and addresses - autocomplete your users' queries as they type. Use the Autocomplete UI widget, or call the API for place predictions.
• Retrieve and display rich information about a place.
• Access high-quality photos of a place.

Differentiate your app by supplying up-to-date local information:

• Add a place to Google's Places database, for retrieval immediately from within your own app and for visibility to other apps after moderation.
• Report a place, to indicate that the device is currently located at a particular place.
• Store the unique place ID for one or more places, and use the ID to retrieve place information on demand.

Other highlights of the API include:

• Accurate place detection at low power with WiFi scan.
• On-device caching: Most requests to the Google Places API for Android may involve a round trip to a Google server, but you can also cache data locally for 30 days.

Supported versions of Android platform

The Google Places API for Android is available for all Android versions that are supported by Google Play services. See the Android guide to supporting different platform versions.

Configure your app

The following configuration steps are required for all apps using the Google Places API for Android.

Set up Google Play services

To access the Google Places API for Android, your app's development project must include Google Play services. Download and install the Google Play services component via the SDK Manager and add the library to your project. For details, see the Android guide to setting up Google Play services.

Add your API key

If you haven't already obtained an API key and enabled the Google Places API for Android, follow the instructions in the signup guide to get one now.

Add your API key to your app manifest as shown in the following code sample, replacing YOUR_API_KEY with your own API key:

<application>
  ...
  <meta-data
      android:name="com.google.android.geo.API_KEY"
      android:value="YOUR_API_KEY"/>
</application>

Request an uplift in usage limits

Usage of the Google Places API for Android is free and unlimited for all apps. However, to ensure fair use by all apps, there are tiered query limits on some methods.

The Google Places API for Android enforces a default limit of 1 000 requests per 24 hour period. If your app exceeds the limit, the app will start failing.

There is a further checkpoint when the app reaches 150 000 requests per 24 hour period. If your app exceeds the limit, the app will start failing again.

Please take steps to increase your limit early if you expect to exceed the default number of requests allowed. See the usage limits guide.

Connect to the Places API

The following interfaces provide the primary entry points to the Google Places API for Android:

• The GeoDataApi provides access to Google's database of local place and business information.
• The PlaceDetectionApi provides quick access to the device's current place, and offers the opportunity to report the location of the device at a particular place.

To connect to the APIs, you need to create an instance of the Google Play services API client. In your fragment's or activity's onCreate() method, create an instance of Google API Client using GoogleApiClient.Builder. Use the builder to add the required APIs, as shown in the following code sample:

import com.google.android.gms.common.api.GoogleApiClient;
import com.google.android.gms.common.api.GoogleApiClient.OnConnectionFailedListener;
import android.support.v4.app.FragmentActivity;

public class MyActivity extends FragmentActivity 
        implements OnConnectionFailedListener {
    private GoogleApiClient mGoogleApiClient;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        mGoogleApiClient = new GoogleApiClient
                .Builder(this)
                .addApi(Places.GEO_DATA_API)
                .addApi(Places.PLACE_DETECTION_API)
                .enableAutoManage(this, this)
                .build();
    }

    // TODO: Please implement GoogleApiClient.OnConnectionFailedListener to
    // handle connection failures.
}

As shown in the code sample, the Places class provides tokens that you can pass to GoogleApiClient.Builder to enable the GeoDataApi and PlaceDetectionApi.

For details about using the client, see the Android guide to Accessing Google APIs. In particular, see the guides to starting a connection and handling connection failures, for more information about addConnectionCallbacks() and addOnConnectionFailedListener().