Place Details (New)

Select platform: Android iOS JavaScript Web Service

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.

Swift

// 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))")
})

Objective-C

// 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);
  }
}];

Places Swift SDK for iOS (Preview)

// 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.

Get open status

The GMSPlacesClient object contains a member function called isOpenWithRequest (isOpenRequest in Swift and isPlaceOpenRequest in GooglePlacesSwift) that returns a response indicating whether the place is currently open, based on the time specified in the call.

This method takes a single argument of type GMSPlaceIsOpenWithRequest that contains:

  • A GMSPlace object, or a string specifying a place ID. For more information on creating the Place object with the necessary fields, see Place details.
  • An optional NSDate (Obj-C) or Date (Swift) object specifying the time you would like to check. If no time is specified, the default is now.
  • A GMSPlaceOpenStatusResponseCallback method to handle the response.
  • >

The GMSPlaceIsOpenWithRequest method requires the following fields to be set in the GMSPlace object:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

If these fields are not provided in the Place object, or if you pass a place ID, the method uses GMSPlacesClient GMSFetchPlaceRequest: to fetch them.

isOpenWithRequest response

isOpenWithRequest returns a GMSPlaceIsOpenResponse object containing a boolean value named status that indicates whether the business is open, closed, or if the status is unknown.

Language Value if open Value if closed Value if status unknown
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (Preview) true false nil

Billing for isOpenWithRequest

  • The GMSPlacePropertyUTCOffsetMinutes and GMSPlacePropertyBusinessStatus fields are charged under the Basic Data SKU. The rest of the Opening Hours are charged under the Place Details (Advanced) SKU.
  • If your GMSPlace object already has these fields from a previous request, you won't be charged again.

Example: Make a GMSPlaceIsOpenWithRequest request

The following example shows how to initialize a GMSPlaceIsOpenWithRequest within an existing GMSPlace object.

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

GooglePlacesSwift

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

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:

Swift

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

Objective-C

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

Places Swift SDK for iOS (Preview)

// 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.