Get Started Contact sales

GooglePlaces Framework Reference

  • GMSPlacesClient provides methods for searching, retrieving details, and interacting with places data using the Google Places SDK for iOS.

  • Access the shared instance via [GMSPlacesClient sharedClient] and ensure all calls are made from the main thread.

  • Key functionalities include place lookups, autocomplete suggestions, photo retrieval, and current place estimation.

  • Methods utilize callbacks for asynchronous operations, invoked on the main thread unless specified otherwise.

  • Refer to the documentation for detailed information on each method, parameters, and deprecation notices.

GMSPlacesClient

@interface GMSPlacesClient : NSObject

Main interface to the Places SDK. Used for searching and getting details about places. This class should be accessed through the [GMSPlacesClient sharedClient] method.

GMSPlacesClient methods should only be called from the main thread. Calling these methods from another thread will result in an exception or undefined behavior. Unless otherwise specified, all callbacks will be invoked on the main thread.

  • Provides the shared instance of GMSPlacesClient for the Google Places SDK for iOS, creating it if necessary.

    If your application often uses methods of GMSPlacesClient it may want to hold onto this object directly, as otherwise your connection to Google may be restarted on a regular basis.

    Declaration

    Swift

    class func shared() -> Self

    Objective-C

    + (nonnull instancetype)sharedClient;

  • Provides your API key to the Google Places SDK for iOS. This key is generated for your application via the Google Cloud Platform Console, and is paired with your application’s bundle ID to identify it. This should be called by your application before using GMSPlacesClient (e.g., in application:didFinishLaunchingWithOptions:).

    Declaration

    Swift

    class func provideAPIKey(_ key: String) -> Bool

    Objective-C

    + (BOOL)provideAPIKey:(nonnull NSString *)key;

    Return Value

    YES if the APIKey was successfully provided.

  • Provides an App Check token provider to the Google Places SDK for iOS. This should be called by your application before using GMSPlacesClient (for example, in application:didFinishLaunchingWithOptions:). If you do not provide a token provider, the SDK will not use the token provider.

    Declaration

    Swift

    class func setAppCheckTokenProvider(_ provider: any GMSPlacesAppCheckTokenProvider)

    Objective-C

    + (void)setAppCheckTokenProvider:
    (nonnull id<GMSPlacesAppCheckTokenProvider>)provider;

  • Returns the open source software license information for the Google Places SDK for iOS. This information must be made available within your application.

    Declaration

    Swift

    class func openSourceLicenseInfo() -> String

    Objective-C

    + (nonnull NSString *)openSourceLicenseInfo;

  • Returns the version for this release of the Google Places SDK for iOS.. For example, “1.0.0”.

    Declaration

    Swift

    class func sdkVersion() -> String

    Objective-C

    + (nonnull NSString *)SDKVersion;

  • Returns the long version for this release of the Google Places SDK for iOS.. For example, “1.0.0 (102.1)”.

    Declaration

    Swift

    class func sdkLongVersion() -> String

    Objective-C

    + (nonnull NSString *)SDKLongVersion;

  • Deprecated

    This method is replaced by fetchPlaceWithRequest:callback: and will be removed in a future release.

    Get details for a place. This method is non-blocking.

    Declaration

    Swift

    func lookUpPlaceID(_ placeID: String, callback: @escaping GMSPlaceResultCallback)

    Objective-C

    - (void)lookUpPlaceID:(nonnull NSString *)placeID
             callback:(nonnull GMSPlaceResultCallback)callback;

    Parameters

    placeID

    The place ID to look up.
    callback

    The callback to invoke with the lookup result.

  • Find Autocomplete suggestions from text query. Results may optionally be biased towards a certain location or restricted to an area. This method is non-blocking.

    The supplied callback will be invoked with an array of autocompletion suggestions upon success and an NSError upon an error.

    Declaration

    Swift

    func fetchAutocompleteSuggestions(from request: GMSAutocompleteRequest, callback: @escaping GMSAutocompleteSuggestionsCallback)

    Objective-C

    - (void)
    fetchAutocompleteSuggestionsFromRequest:
        (nonnull GMSAutocompleteRequest *)request
                                   callback:
                                       (nonnull
                                            GMSAutocompleteSuggestionsCallback)
                                           callback;

    Parameters

    request

    The GMSAutocompleteRequest request for autocomplete.
    callback

    The callback to invoke with the suggestions.

  • Deprecated

    This method is replaced by fetchPhotoWithRequest:callback: and will be removed in a future release.

    Loads the image for a specific photo at its maximum size.

    Image data may be cached by the SDK. If the requested photo does not exist in the cache then a network lookup will be performed.

    Declaration

    Swift

    func loadPlacePhoto(_ photoMetadata: GMSPlacePhotoMetadata, callback: @escaping GMSPlacePhotoImageResultCallback)

    Objective-C

    - (void)loadPlacePhoto:(nonnull GMSPlacePhotoMetadata *)photoMetadata
              callback:(nonnull GMSPlacePhotoImageResultCallback)callback;

    Parameters

    photoMetadata

    The GMSPlacePhotoMetadata for which to load a UIImage.
    callback

    The callback to invoke with the loaded UIImage.

  • Deprecated

    This method is replaced by fetchPhotoWithRequest:callback: and will be removed in a future release.

    Loads the image for a specific photo, scaled to fit the given maximum dimensions.

    The image will be scaled to fit within the given dimensions while maintaining the aspect ratio of the original image. This scaling is performed server-side.

    If the scale parameter is not 1.0 maxSize will be multiplied by this value and the returned UIImage will be set to have the specified scale. This parameter should be set to the screen scale if you are loading images for display on screen.

    Image data may be cached by the SDK. If the requested photo does not exist in the cache then a network lookup will be performed.

    NOTE: After applying the scale factor the dimensions in maxSize will be rounded up to the nearest integer before use. If an image is requested which is larger than the maximum size available a smaller image may be returned.

    Declaration

    Swift

    func loadPlacePhoto(_ photoMetadata: GMSPlacePhotoMetadata, constrainedTo maxSize: CGSize, scale: CGFloat, callback: @escaping GMSPlacePhotoImageResultCallback)

    Objective-C

    - (void)loadPlacePhoto:(nonnull GMSPlacePhotoMetadata *)photoMetadata
     constrainedToSize:(CGSize)maxSize
                 scale:(CGFloat)scale
              callback:(nonnull GMSPlacePhotoImageResultCallback)callback;

    Parameters

    photoMetadata

    The GMSPlacePhotoMetadata for which to load a UIImage.
    maxSize

    The maximum size of the image.
    scale

    The scale to load the image at.
    callback

    The callback to invoke with the loaded UIImage.

  • Deprecated

    This method is replaced by searchNearbyWithRequest:callback: and will be removed in a future release.

    Returns an estimate of the place where the device is currently known to be located.

    Generates a place likelihood list based on the device’s last estimated location. The supplied callback will be invoked with this likelihood list upon success and an NSError upon an error.

    NOTE: This method requires that your app has permission to access the current device location. Before calling this make sure to request access to the users location using [CLLocationManager requestWhenInUseAuthorization] or [CLLocationManager requestAlwaysAuthorization]. If you do call this method and your app does not have the correct authorization status, the callback will be called with an error.

    Declaration

    Swift

    func currentPlace(callback: @escaping GMSPlaceLikelihoodListCallback)

    Objective-C

    - (void)currentPlaceWithCallback:
    (nonnull GMSPlaceLikelihoodListCallback)callback;

    Parameters

    callback

    The callback to invoke with the place likelihood list.

  • Deprecated

    This method is replaced by searchNearbyWithRequest:callback: and will be removed in a future release.

    Find place likelihoods using the user’s current location. This method is non-blocking.

    The supplied callback will be invoked with an array of places with likelihood scores upon success and an NSError upon an error.

    Declaration

    Swift

    func findPlaceLikelihoodsFromCurrentLocation(withPlaceFields placeFields: GMSPlaceField, callback: @escaping GMSPlaceLikelihoodsCallback)

    Objective-C

    - (void)
    findPlaceLikelihoodsFromCurrentLocationWithPlaceFields:
        (GMSPlaceField)placeFields
                                                  callback:
                                                      (nonnull
                                                           GMSPlaceLikelihoodsCallback)
                                                          callback;

    Parameters

    placeFields

    The individual place fields requested for the place objects in the list.
    callback

    The callback to invoke with place likelihoods.

  • Deprecated

    This method is replaced by fetchAutocompleteSuggestionsFromRequest:callback: and will be removed in a future release.

    Find Autocomplete predictions from text query. Results may optionally be biased towards a certain location or restricted to an area. This method is non-blocking.

    The supplied callback will be invoked with an array of autocompletion predictions upon success and an NSError upon an error.

    Declaration

    Swift

    func findAutocompletePredictions(fromQuery query: String, filter: GMSAutocompleteFilter?, sessionToken: GMSAutocompleteSessionToken?, callback: @escaping GMSAutocompletePredictionsCallback)

    Objective-C

    - (void)
    findAutocompletePredictionsFromQuery:(nonnull NSString *)query
                                  filter:
                                      (nullable GMSAutocompleteFilter *)filter
                            sessionToken:
                                (nullable GMSAutocompleteSessionToken *)
                                    sessionToken
                                callback:
                                    (nonnull GMSAutocompletePredictionsCallback)
                                        callback;

    Parameters

    query

    The partial text to autocomplete.
    filter

    The filter to apply to the results. This parameter may be nil.
    sessionToken

    The GMSAutocompleteSessionToken to associate request to a billing session.
    callback

    The callback to invoke with the predictions.

  • Deprecated

    This method is replaced by fetchPlaceWithRequest:callback: and will be removed in a future release.

    Gets the metadata for up to 10 photos associated with a place.

    Photos are sourced from a variety of locations, including business owners and photos contributed by Google+ users. In most cases, these photos can be used without attribution, or will have the required attribution included as a part of the image. However, you must use the attributions property in the response to retrieve any additional attributions required, and display those attributions in your application wherever you display the image. A maximum of 10 photos are returned.

    Multiple calls of this method will probably return the same photos each time. However, this is not guaranteed because the underlying data may have changed.

    This method performs a network lookup.

    Declaration

    Swift

    func lookUpPhotos(forPlaceID placeID: String, callback: @escaping GMSPlacePhotoMetadataResultCallback)

    Objective-C

    - (void)lookUpPhotosForPlaceID:(nonnull NSString *)placeID
                      callback:
                          (nonnull GMSPlacePhotoMetadataResultCallback)callback;

    Parameters

    placeID

    The place ID for which to look up photos.
    callback

    The callback to invoke with the lookup result.

  • Deprecated

    This method is replaced by isOpenWithRequest:callback: and will be removed in a future release.

    Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the current time. This method is non-blocking.

    Declaration

    Swift

    func isOpen(withPlaceID placeID: String, callback: @escaping GMSPlaceOpenStatusCallback)

    Objective-C

    - (void)isOpenWithPlaceID:(nonnull NSString *)placeID
                 callback:(nonnull GMSPlaceOpenStatusCallback)callback;

    Parameters

    placeID

    The place ID to look up.
    callback

    The callback to invoke with the place result.

  • Deprecated

    This method is replaced by isOpenWithRequest:callback: and will be removed in a future release.

    Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the specified NSDate. This method is non-blocking.

    Declaration

    Swift

    func isOpen(withPlaceID placeID: String, date: Date, callback: @escaping GMSPlaceOpenStatusCallback)

    Objective-C

    - (void)isOpenWithPlaceID:(nonnull NSString *)placeID
                     date:(nonnull NSDate *)date
                 callback:(nonnull GMSPlaceOpenStatusCallback)callback;

    Parameters

    placeID

    The place ID to look up.
    date

    The NSDate to determine open status for.
    callback

    The callback to invoke with the place result.

  • Deprecated

    This method is replaced by isOpenWithRequest:callback: and will be removed in a future release.

    Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the current time. Only requests additional fields if the GMSPlace does not have all necessary fields, otherwise GMSPlaceOpenStatus will be returned in the callback immediately. This method is non-blocking.

    Declaration

    Swift

    func isOpen(with place: GMSPlace, callback: @escaping GMSPlaceOpenStatusCallback)

    Objective-C

    - (void)isOpenWithPlace:(nonnull GMSPlace *)place
               callback:(nonnull GMSPlaceOpenStatusCallback)callback;

    Parameters

    place

    The GMSPlace to look up.
    callback

    The callback to invoke with the place result.

  • Deprecated

    This method is replaced by isOpenWithRequest:callback: and will be removed in a future release.

    Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the specified NSDate. Only requests additional fields if the GMSPlace does not have all necessary fields, otherwise GMSPlaceOpenStatus will be returned in the callback immediately. This method is non-blocking.

    Declaration

    Swift

    func isOpen(with place: GMSPlace, date: Date, callback: @escaping GMSPlaceOpenStatusCallback)

    Objective-C

    - (void)isOpenWithPlace:(nonnull GMSPlace *)place
                   date:(nonnull NSDate *)date
               callback:(nonnull GMSPlaceOpenStatusCallback)callback;

    Parameters

    place

    The GMSPlace to look up.
    date

    The NSDate to determine open status for.
    callback

    The callback to invoke with the place result.

  • Deprecated

    This method is replaced by fetchPlaceWithRequest:callback:callback: and will be removed in a future release.

    Fetch details for a place. This method is non-blocking.

    Declaration

    Swift

    func fetchPlace(fromPlaceID placeID: String, placeFields: GMSPlaceField, sessionToken: GMSAutocompleteSessionToken?, callback: @escaping GMSPlaceResultCallback)

    Objective-C

    - (void)fetchPlaceFromPlaceID:(nonnull NSString *)placeID
                  placeFields:(GMSPlaceField)placeFields
                 sessionToken:
                     (nullable GMSAutocompleteSessionToken *)sessionToken
                     callback:(nonnull GMSPlaceResultCallback)callback;

    Parameters

    placeID

    The place ID to look up.
    placeFields

    The individual place fields requested for the place objects in the list.
    sessionToken

    The GMSAutocompleteSessionToken to associate request to a billing session.
    callback

    The callback to invoke with the lookup result.

  • Gets the open status for a place. Gets details for a place including all properties necessary to determine GMSPlaceOpenStatus at the specified NSDate. This method is non-blocking.

    Declaration

    Swift

    func isOpen(with isOpenRequest: GMSPlaceIsOpenRequest, callback: @escaping GMSPlaceOpenStatusResponseCallback)

    Objective-C

    - (void)isOpenWithRequest:(nonnull GMSPlaceIsOpenRequest *)isOpenRequest
                 callback:(nonnull GMSPlaceOpenStatusResponseCallback)callback;

    Parameters

    isOpenRequest

    The request to determine the open status for a given place.
    callback

    The callback to invoke with the open status response.

  • Search for places by text and restrictions. This method is non-blocking.

    Declaration

    Swift

    func searchByText(with textSearchRequest: GMSPlaceSearchByTextRequest, callback: @escaping GMSPlaceSearchByTextResultCallback)

    Objective-C

    - (void)searchByTextWithRequest:
            (nonnull GMSPlaceSearchByTextRequest *)textSearchRequest
                       callback:
                           (nonnull GMSPlaceSearchByTextResultCallback)callback;

    Parameters

    textSearchRequest

    GMSPlaceSearchByTextRequest The text request to use for the query.
    callback

    The callback to invoke with the lookup result.

  • Get a place using a request object. This method is non-blocking.

    Declaration

    Swift

    func fetchPlace(with fetchPlaceRequest: GMSFetchPlaceRequest, callback: @escaping GMSPlaceResultCallback)

    Objective-C

    - (void)fetchPlaceWithRequest:(nonnull GMSFetchPlaceRequest *)fetchPlaceRequest
                     callback:(nonnull GMSPlaceResultCallback)callback;

    Parameters

    fetchPlaceRequest

    GMSFetchPlaceRequest The fetch place request to use for the query.
    callback

    The callback to invoke with the place result.

  • Request a photo using fetch photo request. This method is non-blocking.

    Declaration

    Swift

    func fetchPhoto(with fetchPhotoRequest: GMSFetchPhotoRequest, callback: @escaping GMSFetchPhotoResultCallback)

    Objective-C

    - (void)fetchPhotoWithRequest:(nonnull GMSFetchPhotoRequest *)fetchPhotoRequest
                     callback:(nonnull GMSFetchPhotoResultCallback)callback;

    Parameters

    fetchPhotoRequest

    GMSFetchPhotoRequest The photo request to use.
    callback

    The callback to invoke with the NSURL result.

  • Search for places near a location and restriction. This method is non-blocking.

    Declaration

    Swift

    func searchNearby(with searchNearbyRequest: GMSPlaceSearchNearbyRequest, callback: @escaping GMSPlaceSearchNearbyResultCallback)

    Objective-C

    - (void)searchNearbyWithRequest:
            (nonnull GMSPlaceSearchNearbyRequest *)searchNearbyRequest
                       callback:
                           (nonnull GMSPlaceSearchNearbyResultCallback)callback;

    Parameters

    searchNearbyRequest

    GMSPlaceSearchNearbyRequest The search nearby request to use for the query.
    callback

    The callback to invoke with the lookup result.

  • Adds a usage attribution ID to the initializer, which helps Google understand which libraries and samples are helpful to developers, such as usage of a marker clustering library. To opt out of sending the usage attribution ID, it is safe to delete this function call or replace the value with an empty string.

    Declaration

    Swift

    class func addInternalUsageAttributionID(_ internalUsageAttributionID: String)

    Objective-C

    + (void)addInternalUsageAttributionID:
    (nonnull NSString *)internalUsageAttributionID;

    Parameters

    internalUsageAttributionId

    The usage attribution ID to add