Choose your API version

Places API supports two API versions: Places API are the existing APIs and Places API (New) are the next generation version of the APIs.

With the release of Places API (New), your first task is to decide which set of APIs to use. This is true if you are a new customer or an existing customer already using the APIs. Use this guide to understand the key differences 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 are currently 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 enable on your API key controls the APIs used by your app:

  • Places API: Enables the existing APIs. If only Places API is enabled for the project associated with the API key used for your app, your app won't have access to the new APIs.

  • Places API (New): Enables all new APIs and features described in Key features added to Places SDK for iOS (New). Your app won't have access to the existing APIs.

  • Both: Enables all the features and APIs for both Places SDK for iOS (New) and Places 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 the following migration guides for each API:

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 the service infrastructure on Google Cloud. This implementation brings with it a more secure and trusted platform with enhanced security options like OAuth. This standard API design brings a level of consistency across the APIs that improve the efficiency of 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 only pay for the data you use. Simplified pricing is implemented using a field mask.

With Place Details (New), Nearby Search (New), and Text Search (New) you use the field mask to control the list of fields to return in the response. You are then only billed for the data requested. Using field masking is a good design practice to ensure that you don't request unnecessary data, which helps to avoid unnecessary processing time and billing charges.

Consistent response data for a place

With the existing APIs, the Place Details, Nearby Search, and Text Search APIs 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 have a single type value that is specified as the place's primary type, as listed in Table A.

In addition, the new API adds the place types shown in the table below. You can use these new types, and the existing types, in a search with Nearby Search (New) and Text Search (New). The new types are all 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:

  • country
  • administrative_area_level_1
  • administrative_area_level_2
  • postal_code
  • locality

Dynamic place data

Places API (New) supports dynamic response data, such as the availability of an EV charging station or the latest fuel prices for a gas station. Use these response fields to create dynamic user experiences.

Which API do you choose?

Before you can start app development, you must choose your API:

  1. If you are a new customer just getting started with Places API, then start with the new APIs.

  2. If you are a new customer and there is not yet a replacement for an existing API, such as Place Autocomplete or Query Autocomplete, then you can use a combination of new and existing APIs.

  3. If you are an existing customer, you can continue using the existing APIs. However, to take advantage of the performance improvements and the feature enhancements of the Places API (New), you can migrate to the new APIs.

    For more information on migration, see Migration overview.