Places SDK for Android version 3.4.0 supports two SDK versions: Places SDK for Android is the existing SDK and Places SDK for Android (New) is the next generation version of the SDK.
With the release of Places SDK for Android version 3.4.0, your first task is to decide which SDK to use. This is true if you are a new customer or an existing customer already using the SDK. Use this guide to understand the key differences between the two SDKs.
How to select your SDK version
On the backend, Places SDK for Android relies on the Places API service, either Places API (New) or Places API. Before you can use Places SDK for Android, you must enable the Places API service in your Google Cloud project.
For Android, there are two actions you take to determine which APIs you can use in your app:
In your project, you must enable Places API (New), Places API, or both on your API key depending on which you intend to use in your app.
Initialize your app by calling either the
Places.initializeWithNewPlacesApiEnabled()
orPlaces.initialize()
method.
Select you SDK
The version of the Places API service that you enable controls the SDK version used by your app:
Both: Enables all features for both Places SDK for Android and Places SDK for Android (New). Use the
Places.initializeWithNewPlacesApiEnabled()
andPlaces.initialize()
method to control the available features.Places API: Enables the existing Places SDK for Android. You don't have access to the new features added in Places SDK for Android version 3.4.0.
Places API (New): Enables Places SDK for Android (New) and all new features described in Key features added to Places SDK for Android (New) but does not enable existing features such as Current Place and Place Autocomplete.
For more information on selecting the Places API service, see Set up your Google Cloud project.
Initialize your app
When you initialize your app, you must call either the
Places.initializeWithNewPlacesApiEnabled()
or the Places.initialize()
method.
The following table shows the effects of enabling each SDK and calling each
initialize method. For example, if you enable Places SDK (New) and call
Places.initializeWithNewPlacesApiEnabled()
, you can use all of the new APIs
and all of the existing APIs.
If you enable Places SDK (New) and call
Places.initialize()
, you cannot use the new features of Place Details and
Place Photos, but can call the new Text Search. If you don't enable Places API,
you cannot access old version of Place Details but you can still call the new
Text Search.
Version | APIs | SDK Enabled on API key | Initialization method | ||
---|---|---|---|---|---|
Places API | Places API (New) | initialize() |
initializeWithNewPlacesApiEnabled() |
||
v3.3.0 | Places Details | ||||
Places Details (New) | |||||
Photo Metadata (New) | |||||
Text Search (New) | Either method | ||||
v3.4.0 | Photo Uri (New) | ||||
Photo bitmap | Either method | ||||
CurrentPlace | Either method | ||||
Autocomplete | Either method |
Which SDK do you choose?
To help decide which version to choose:
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 a Kotlin developer, you can use either SDK but the new features in Places SDK for Android (New) are only available in Java in version 3.4.0.
If you are an existing customer and are using session tokens, continue using the existing SDK. Places SDK for Android (New) does not currently support session tokens.
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 can use the new SDK.
There is no migration necessary when moving to the new SDK. You only have to:
- Enable Places API (New) on the API key used in your app. For more information, see Using API Keys.
In the
dependencies
section of your module-levelbuild.gradle
file, update theplaces
dependency and add thekotlin-bom
dependency:dependencies { implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0")) implementation 'com.google.android.libraries.places:places:3.3.0' }
For more information on the
kotlin-bom
dependency, see Usage of the latest kotlin-stdlib version in transitive dependencies.- Update your existing app to call the new
Places.initializeWithNewPlacesApiEnabled()
method to initialize your app. For more information, see Initialize the Places API client.
Your existing apps continue to work unchanged, but you can now take advantage of all new SDK features.
Key features added to 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 Text Search service
Text Search 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 and Place Photos
Place Details now includes the new Review class in the response
Place
object. The Place class contains the newgetReviews()
method to support this field. CallgetReviews()
to return up to five reviews for a place.Place Photo adds the
AuthorAttributions
to thePhotoMetadata
class.AuthorAttributions
contains aList
ofAuthorAttribution
objects.
New URI response added to Place Photos
You can now use Place Photos 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 |
country
administrative_area_level_1
administrative_area_level_2
postal_code
locality