Place Details (New)

The Places SDK for iOS (New) provides your app with rich information about places, including the place's name and address, the geographical location specified as latitude/longitude coordinates, the type of place (such as night club, pet store, museum), and more. To access this information for a specific place, you can use the place ID, a stable identifier that uniquely identifies a place.

Get place details

The GMSPlace class contains information about a specific place, including all of the data fields shown in Place Data Fields (New). Get a GMSPlace object by calling GMSPlacesClient fetchPlaceWithRequest:, passing a GMSFetchPlaceRequest object and a callback method of type GMSPlaceResultCallback.

The GMSFetchPlaceRequest object specifies:

• (Required) The place ID, a unique identifier for a place in the Google Places database and on Google Maps.
• (Required) The list of fields to return in the GMSPlace object, also called the field mask, as defined by GMSPlaceProperty. If you don't specify at least one field in the field list, or if you omit the field list, then the call returns an error.
• (Optional) The region code used to format the response.
• (Optional) The session token used to end an Autocomplete (New) session.

Make a Place Details request

This example gets a place by ID, passing the following parameters:

• The place ID of ChIJV4k8_9UodTERU5KXbkYpSYs.
• A field list specifying to return the place name and website URL.
• A GMSPlaceResultCallback to handle the result.

The API invokes the specified callback method, passing in a GMSPlace object. If the place is not found, the place object is nil.

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"

// Specify the place data types to return.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue}

// Create the GMSFetchPlaceRequest object.
let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil)

client.fetchPlace(with: fetchPlaceRequest, callback: {
  (place: GMSPlace?, error: Error?) in
  guard let place, error == nil else { return }
  print("Place found: \(String(describing: place.name))")
})

// A hotel in Saigon with an attribution.
NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs";

// Specify the place data types to return.
NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite];

// Create the GMSFetchPlaceRequest object.
GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil];

[placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

// A hotel in Saigon with an attribution.
let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs"
let fetchPlaceRequest = FetchPlaceRequest(
  placeID: placeID,
  placeProperties: [.name, .website]
)
switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
case .success(let place):
  // Handle place
case .failure(let placesError):
  // Handle error
}

Place Details response

Place Details returns a GMSPlace object containing details about the place. Only those fields specified in the field list are populated in the GMSPlace object.

Along with the data fields, the GMSPlace object in the response contains the following member functions:

• isOpen calculates whether a place is open at the given time.
• isOpenAtDate calculates whether a place is open on a given date.

Required parameters

Use the GMSFetchPlaceRequest object to specify the required parameters.

Place ID

The place ID used in the Places SDK for iOS is the same identifier as used in the Places API, Places SDK for Android and other Google APIs. Each place ID can refer to only one place, but a single place can have more than one place ID.

There are circumstances which may cause a place to get a new place ID. For example, this may happen if a business moves to a new location.

When you request a place by specifying a place ID, you can be confident that you will always receive the same place in the response (if the place still exists). Note, however, that the response may contain a place ID that is different from the one in your request.

Field list

When you request place details, you must specify the data to return in the GMSPlace object for the place as a field mask. To define the field mask pass an array of values from GMSPlaceProperty to the GMSFetchPlaceRequest object. 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.

Specify one or more of the following fields:

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

  GMSPlacePropertyPlaceID, GMSPlacePropertyName, GMSPlacePropertyPhotos

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

  GMSPlacePropertyAddressComponents, GMSPlacePropertyFormattedAddress, GMSPlacePropertyCoordinate, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyViewport

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

  GMSPlacePropertyBusinessStatus, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyWheelchairAccessibleEntrance

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

  GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel, GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

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

  GMSPlacePropertyCurbsidePickup, GMSPlacePropertyDelivery, GMSPlacePropertyDineIn, GMSPlacePropertyEditorialSummary, GMSPlacePropertyReservable, GMSPlacePropertyReviews, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

The following example passes a list of two field values to specify that the GMSPlace object returned by a request contains the name and placeID fields:

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]
  

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
  

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]
    

Optional parameters

Use the GMSFetchPlaceRequest object to specify the optional parameters.

regionCode

The region code used to format the response, specified as a two-character CLDR code value. This parameter can also have a bias effect on the search results. There is no default value.

If the country name of the address field in the response matches the region code, the country code is omitted from 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.

sessionToken

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.

Display attributions in your app

When your app displays information obtained from GMSPlacesClient, such as photos and reviews, the app must also display the required attributions.

For example, the reviews property of the GMSPlacesClient object contains an array of up to five GMSPlaceReview objects. Each GMSPlaceReview object can contain attributions and author attributions. If you display the review in your app, then you must also display any attribution or author attribution.

For more information, see the documentation on attributions.