Places API supports two API versions:Places API are theexisting APIs and Places API(New) are the nextgeneration version of the APIs.
With the release of Places API (New), your first task is to decide whichset of APIs to use. This is true if you are a new customer or an existingcustomer already using the APIs. Use this guide to understand the keydifferences between the two APIs.
List of APIs
The following table lists both sets of APIs. If you are an existing customer,use this table to determine the new API that replaces an API that you arecurrently using.
| Places API | Places API (New) | Note |
|---|---|---|
| Find Place | Text Search (New) | There is no new version of Find Place. Text Search (New) has replaced it. |
| Nearby Search | Nearby Search (New) | All requests using the existing API that include a text query should use Text Search (New) because Nearby Search (New) does not support text input. |
| Text Search | Text Search (New) | |
| Place Details | Place Details (New) | |
| Place Photo | Place Photo (New) | |
| Place Autocomplete | Autocomplete (New) | |
| Query Autocomplete | Autocomplete (New) | Capabilities added to Autocomplete (New) |
The version of the Places API service that you enableon your API key controls the APIs used by your app:
Places API: Enables the existing APIs. If onlyPlaces API is enabled for the project associated withthe API key used for your app, your app won't have access to the new APIs.
Places API (New): Enables all new APIs andfeatures described in Key features added toPlaces SDK for iOS (New). Your app won'thave access to the existing APIs.
Both: Enables all the features and APIs for bothPlaces SDK for iOS (New) andPlaces SDK for iOS.
For more information on selecting the Places API service,see Set up your Google Cloud project.
Migrate to the new APIs
If you are using an existing API and want to migrate to the new API, see thefollowing migration guides for each API:
- Migrate to Nearby Search (New)
- Migrate to Text Search (New)
- Migrate to Place Details (New)
- Migrate to Place Photo (New)
- Migrate to Autocomplete (New)
Key features added to Places API (New)
This section covers key features added to Places API (New).
Implemented on the Google Cloud standard platform
Places API (New) is implemented on theservice infrastructure on Google Cloud. This implementation brings with it a more secure and trustedplatform with enhanced security options likeOAuth. This standard APIdesign brings a level of consistency across the APIs that improve the efficiencyof development with Places API (New).
Improved performance
Places API (New) provides improved performance,making it worthwhile to replace apps that use the existing Places API.
Simplified pricing
Pricing is simplified with Places API (New) so that you onlypay for the data you use. Simplified pricing is implemented using afield mask.
With Place Details (New),Nearby Search (New), andText Search (New) you use the field mask to control thelist of fields to return in the response. You are then only billed for the datarequested. Using field masking is a good design practice to ensure that youdon't request unnecessary data, which helps to avoid unnecessary processing timeand billing charges.
Consistent response data for a place
With the existing APIs, the Place Details,Nearby Search, and Text SearchAPIs returned different response data for a place. Places API (New)standardizes the response so these APIs all return the same data for a place.
Expanded place types
The API response can now contain a place's primary type. Every place can havea single type value that is specified as the place's primary type, as listed inTable A.
In addition, the new API adds the place types shown in the table below. You canuse these new types, and the existing types, in a search withNearby Search (New) andText Search (New). The new types are all included inTable A.
| Type | |||
|---|---|---|---|
| american_restaurant | discount_store | ice_cream_shop | sandwich_shop |
| amusem*nt_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 typesfrom 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 asearch:
countryadministrative_area_level_1administrative_area_level_2postal_codelocality
Dynamic place data
Places API (New) supports dynamic response data, such as the availabilityof an EV charging station or the latest fuel prices for a gas station. Usethese response fields to create dynamic user experiences.
Which API do you choose?
Before you can start app development, you must choose your API:
If you are a new customer just getting started with Places API,then start with the new APIs.
If you are a new customer and there is not yet a replacement for anexisting API, such as Place Autocomplete or QueryAutocomplete, then you can use a combination of new and existing APIs.
If you are an existing customer, you can continue using the existingAPIs. However, to take advantage of the performance improvements and thefeature enhancements of the Places API (New), you can migrate to thenew APIs.
For more information on migration, see Migrationoverview.
