The Places SDK for Android features that are available in your app are determined by a combination of the SDK version number (e.g. 3.5.0) that you specify in your app configuration, the APIs enabled on your API key, and how you initialize your app. This guide explains the differences between versions and how to select which versions are enabled in your app.
SDK version numbers
The version number of the SDK that you specify in your app-level build.gradle file determines whether your app has access to features that were added in a particular release. For example, Autocomplete (New) is only available in SDK version 3.5.0 or greater.
For more information on changes introduced in each SDK version, see the Places SDK for Android release notes.
Places API versions for the Places SDK for Android
In addition to specifying a SDK version number, you must also select the Places API service that the SDK calls in the Google Cloud Console: either Places API or Places API (New). Together with the SDK version number, the API service that you select determines which version of specific features are available in your app, such as Autocomplete or Autocomplete (New). While you can only specify one SDK version number, you can enable both the Places API and Places API (New) on your API key at the same time, and then select which service the SDK calls through the method you use to initialize the SDK in your app. However, in most cases, you will want to enable the Places API (New) and use the (New) versions of the SDK features in your app.
Select your SDK version and API services
To select which SDK features are available in your app, do the following:
- In your Google Cloud project, enable the Places API, Places API (New), or both. For more information, see Enable APIs
- In your API key restrictions, enable the Places API, Places API (New), or both. For more information, see Restricting API keys.
In the app-level build.gradle file, specify a version number. For more information, see Installation.
Initialize your app by calling either the
Places.initializeWithNewPlacesApiEnabled()orPlaces.initialize()method.
For more information on selecting the Places API service, see Set up your Google Cloud project.
SDK features available in each version
The following table shows which SDK and API versions are required for each SDK feature:
| Feature | Places API enabled on API key | Initialization method | Minimum SDK version |
|---|---|---|---|
| Autocomplete (New) | Places API (New) | initializeWithNewPlacesApiEnabled() |
3.5.0 |
| Place Details (New) | Places API (New) | initializeWithNewPlacesApiEnabled() |
3.3.0 |
| Nearby Search (New) | Places API (New) | initializeWithNewPlacesApiEnabled() |
3.5.0 |
| Place Photos (New) | Places API (New) | initializeWithNewPlacesApiEnabled() |
3.4.0 |
| Text Search (New) | Places API (New) | initializeWithNewPlacesApiEnabled() |
3.3.0 |
| Place Autocomplete | Places API | initialize() |
|
| Current Place | Places API | initialize() |
|
| Place Details | Places API | initialize() |
|
| Place Photos | Places API | initialize() |
Considerations for choosing which versions to enable
To help decide which version to choose consider the following:
- If you are a new customer just getting started with Places SDK for Android, then start with Places API (New) and the new SDK.
- If you are an existing customer, you can continue using the existing SDK. However, to take advantage of the performance improvements and the feature enhancements of the Places SDK for Android (New), you should use the new SDK. There is no migration necessary when moving to the new SDK, just follow the steps in Select your SDK version and API services.
- In the Places SDK for Android (New), session tokens are available starting in version 3.5.0. For more information, see Session tokens.
- Calls made using Place Autocomplete widgets always call Place Autocomplete, not Place Autocomplete (New); widget calls are not affected by the initialization method.
- Place Photos (New) only returns a URI to a bitmap image, while Place Photos only returns a bitmap image.
- Current Place is only available in the Places SDK for Android, not Places SDK for Android (New).
Enhancements in Places SDK for Android (New)
This section covers key features added to Places SDK for Android (New).
Implemented on the Google Cloud standard platform
Places SDK for Android (New) is implemented on the service infrastructure on Google Cloud. This implementation brings a more secure and trusted platform. This standard design brings a level of consistency across the SDKs that improve the efficiency of development with Places SDK for Android (New).
Improved performance
Places SDK for Android (New) provides improved performance, making it worthwhile to replace apps that use the existing SDK.
New features
The Places SDK for Android (New) includes the latest versions of all of the SDK features:
New Text Search service
Text Search (New) returns information about a set of places based on a string — for example "pizza in New York" or "shoe stores near Ottawa" or "123 Main Street". The service responds with a list of places matching the text string and any location bias that has been set.
New response data added to Placed Details (New) and Place Photos (New)
Place Details (New) now includes the new Review class in the response
Placeobject. The Place class contains the newgetReviews()method to support this field. CallgetReviews()to return up to five reviews for a place.Place Photo (New) adds the
AuthorAttributionsto thePhotoMetadataclass.AuthorAttributionscontains aListofAuthorAttributionobjects.
New URI response added to Place Photos (New)
You can now use Place Photo (New) to return a URI to an image bitmap. Previously, you could only return the image bitmap itself.
Simplified pricing
Pricing is simplified with Places SDK for Android (New) so that you only pay for the data you use. Simplified pricing is implemented using field lists, also called field masks.
With Place Details and Text Search you use field lists to control the list of fields to return in the response. You are then only billed for the data requested. Using a field list is a good design practice to ensure that you don't request unnecessary data, which helps to avoid unnecessary processing time and billing charges.
For detailed pricing information for both SDKs, see Usage and Billing.
Expanded place types
The new SDK adds the place types shown in the following table. These types are returned as part of the Place Details and Text Search response. You can also use these new types, and the existing types, in a search with Text Search. The new types are included in Table A.
| Type | |||
|---|---|---|---|
| american_restaurant | discount_store | ice_cream_shop | sandwich_shop |
| amusement_center | dog_park | indian_restaurant | school_district |
| athletic_field | electric_vehicle_charging_station | indonesian_restaurant | seafood_restaurant |
| auto_parts_store | event_venue | italian_restaurant | ski_resort |
| banquet_hall | extended_stay_hotel | japanese_restaurant | spanish_restaurant |
| barbecue_restaurant | farm | korean_restaurant | sporting_goods_store |
| barber_shop | farmstay | lebanese_restaurant | sports_club |
| bed_and_breakfast | fast_food_restaurant | marina | sports_complex |
| brazilian_restaurant | ferry_terminal | market | steak_house |
| breakfast_restaurant | fitness_center | medical_lab | sushi_restaurant |
| brunch_restaurant | french_restaurant | mediterranean_restaurant | swimming_pool |
| bus_stop | gift_shop | mexican_restaurant | tailor |
| camping_cabin | golf_course | middle_eastern_restaurant | telecommunications_service_provider |
| cell_phone_store | greek_restaurant | motel | thai_restaurant |
| child_care_agency | grocery_store | national_park | transit_depot |
| chinese_restaurant | guest_house | park_and_ride | truck_stop |
| coffee_shop | hair_salon | performing_arts_theater | turkish_restaurant |
| community_center | hamburger_restaurant | pizza_restaurant | vegan_restaurant |
| consultant | heliport | playground | vegetarian_restaurant |
| convention_center | hiking_area | preschool | vietnamese_restaurant |
| cottage | historical_landmark | private_guest_room | visitor_center |
| courier_service | home_improvement_store | ramen_restaurant | wedding_venue |
| cultural_center | hostel | resort_hotel | wholesaler |
| dental_clinic | hotel | rest_stop |
Along with these new types, the Places API (New) moved the following types from Table 2 for the Places API to Table A for the Places API (New). That means you can now use these types as part of a search:
countryadministrative_area_level_1administrative_area_level_2postal_codelocality