Place Details (New)

Select platform: Android iOS JavaScript Web Service

You can request more details about a particular establishment or point of interest by using its place ID and making a Place Details (New) request. Place Details (New) returns more comprehensive information about the indicated place, such as its complete address, phone number, user rating and reviews.

There are many ways to obtain a place ID. You can use:

• Text Search (New)
• Nearby Search (New)
• Autocomplete (New)

Note: Place Details (New) is available in Places SDK for Android version 3.3.0 and later. For more information, see Choose your SDK version. For more information about using the Kotlin APIs added in version 4.0.0, see the Reference Overview.

Place Details (New) requests

You can request place details by calling PlacesClient.fetchPlace() and passing a FetchPlaceRequest object containing a place ID and field list, as well as any optional parameters:

// Define a place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList("INSERT_PLACE_FIELDS_HERE");

// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

Note: For more information on initializing PlacesClient, see Initialize the Places API client.

You can use a CancellationToken to attempt to cancel a request to any of the request classes (for example, FetchPlaceRequest). Cancellation is done on a best-effort basis. Once a cancellation request is issued, no response will be returned. Issuing a cancellation token does NOT guarantee that a particular request will be cancelled, and you may still be charged for the request even if no response is returned.

Place Details (New) responses

Place Details (New) returns data in the form of a Place object, which includes only the fields that you requested using the field list. Place data results cannot be empty, so only place results with data are returned (for example, if a requested place has no photos, the photos field won't be present in the result).

To access data fields, call the corresponding method. For example, to access the place name, call getName().

Required parameters

The required parameters for FetchPlaceRequest are:

• Place ID

  A textual identifier that uniquely identifies a place, returned from a Text Search (New), Nearby Search (New), or Autocomplete (New). For more information about place IDs, see the place ID overview.

• Field list

  When you request a place, you must specify which place data to return. To do this, pass a list of Place.Field values specifying the data to return. There is no default list of returned fields in the response.

  Field lists are a good design practice to ensure that you don't request unnecessary data, which helps to avoid unnecessary processing time and billing charges.This list is an important consideration because it affects the cost for each request. For more information, see Usage and Billing.

  Specify one or more of the following fields:

  • The following fields trigger the Place Details (IDs Only) SKU:

    Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.PHOTO_METADATAS, Place.Field.RESOURCE_NAME
    
    Notes:

    • The Place.Field.NAME field was deprecated in version 4.0 of the Places SDK for Android. Use Place.Field.DISPLAY_NAME instead.
    • The RESOURCE_NAME field contains the place resource name in the form: places/PLACE_ID. Use DISPLAY_NAME to access the text name of the place.

  • The following fields trigger the Place Details (Location Only) SKU:

    Place.Field.ADDRESS_COMPONENTS, ADR_FORMAT_ADDRESS, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION, Place.Field.PLUS_CODE, Place.Field.SHORT_FORMATTED_ADDRESS, Place.Field.TYPES, Place.Field.VIEWPORT
    
    Note:The Place.Field.ADDRESS and Place.Field.LAT_LNG fields were deprecated in version 4.0 of the Places SDK for Android. Use Place.Field.FORMATTED_ADDRESS and Place.Field.LOCATION, respectively, instead.

  • The following fields trigger the Place Details (Basic) SKU:

    Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.BUSINESS_STATUS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.SUB_DESTINATIONS, Place.Field.UTC_OFFSET
    
    Note:The Place.Field.ICON_URL and Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE fields were deprecated in version 4.0 of the Places SDK for Android. Use Place.Field.ICON_MASK_URL and Place.Field.ACCESSIBILITY_OPTIONS, respectively, instead. Place.Field.ACCESSIBILITY_OPTIONS is only available for Place Details (New).

  • The following fields trigger the Place Details (Advanced) SKU:

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    
    Note:The Place.Field.PHONE_NUMBER and Place.Field.USER_RATINGS_TOTAL fields were deprecated in version 4.0 of the Places SDK for Android. Use Place.Field.INTERNATIONAL_PHONE_NUMBER and Place.USER_RATING_COUNT, respectively, instead.

  • The following fields trigger the Place Details (Preferred) SKU:

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  Note: Version 4.0 of Places SDK for Android introduced the deprecation of several Place data fields and the addition of new fields. For more information, see Migrate to the new Place data fields in the Places SDK for Android 4.0 .

Optional parameters

The optional parameters for FetchPlaceRequest are:

• Region code

  The region code used to format the response, specified as a two-character CLDR code value. There is no default value.

  If the country name of the Place.Field.FORMATTED_ADDRESS field in the response matches the regionCode, the country code is omitted from Place.Field.FORMATTED_ADDRESS.

  Most CLDR codes are identical to ISO 3166-1 codes, with some notable exceptions. For example, the United Kingdom's ccTLD is "uk" (.co.uk) while its ISO 3166-1 code is "gb" (technically for the entity of "The United Kingdom of Great Britain and Northern Ireland"). The parameter can affect results based on applicable law.

  To set the region code parameter, call the setRegionCode() method when building the FetchPlaceRequest object.

• Session token

  Session tokens are user-generated strings that track Autocomplete (New) calls as "sessions." Autocomplete (New) uses session tokens to group the query and place selection phases of a user autocomplete search into a discrete session for billing purposes. Session tokens are passed into Place Details (New) calls that follow Autocomplete (New) calls. For more information, see Session tokens.

  To set the session token parameter, call the setSessionToken() method when building the FetchPlaceRequest object.

Place Details example

The following example requests the ID, DISPLAY_NAME, and FORMATTED_ADDRESS fields for the Empire State Building in New York City.

// Define a place ID.
final String placeId = "ChIJaXQRs6lZwokRY6EFpJnhNNE";

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

// Construct a request object, passing the place ID and field list.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

// Pass the request object and make the request
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);