GMSPlacesClient Class Reference


Overview

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.

Public Member Functions

(void) - lookUpPlaceID:callback:
 Get details for a place.
(void) - fetchAutocompleteSuggestionsFromRequest:callback:
 Find Autocomplete suggestions from text query.
(void) - lookUpPhotosForPlaceID:callback:
 Gets the metadata for up to 10 photos associated with a place.
(void) - loadPlacePhoto:callback:
 Loads the image for a specific photo at its maximum size.
(void) - loadPlacePhoto:constrainedToSize:scale:callback:
 Loads the image for a specific photo, scaled to fit the given maximum dimensions.
(void) - currentPlaceWithCallback:
 Returns an estimate of the place where the device is currently known to be located.
(void) - findAutocompletePredictionsFromQuery:filter:sessionToken:callback:
 Find Autocomplete predictions from text query.
(void) - fetchPlaceFromPlaceID:placeFields:sessionToken:callback:
 Fetch details for a place.
(void) - findPlaceLikelihoodsFromCurrentLocationWithPlaceFields:callback:
 Find place likelihoods using the user's current location.
(void) - isOpenWithRequest:callback:
 Gets the open status for a place.
(void) - isOpenWithPlaceID:callback:
 Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the current time.
(void) - isOpenWithPlaceID:date:callback:
 Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the specified NSDate.
(void) - isOpenWithPlace:callback:
 Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the current time.
(void) - isOpenWithPlace:date:callback:
 Gets details for a place including all fields necessary to determine GMSPlaceOpenStatus at the specified NSDate.
(void) - searchByTextWithRequest:callback:
 Search for places by text and restrictions.
(void) - fetchPlaceWithRequest:callback:
 Get a place using a request object.
(void) - fetchPhotoWithRequest:callback:
 Request a photo using fetch photo request.
(void) - searchNearbyWithRequest:callback:
 Search for places near a location and restriction.

Static Public Member Functions

(instancetype) + sharedClient
 Provides the shared instance of GMSPlacesClient for the Google Places SDK for iOS, creating it if necessary.
(BOOL) + provideAPIKey:
 Provides your API key to the Google Places SDK for iOS.
(NSString *) + openSourceLicenseInfo
 Returns the open source software license information for the Google Places SDK for iOS.
(NSString *) + SDKVersion
 Returns the version for this release of the Google Places SDK for iOS.
(NSString *) + SDKLongVersion
 Returns the long version for this release of the Google Places SDK for iOS.

(Note that these are not member functions.)

typedef void(^ GMSPlaceResultCallback )(GMSPlace *_Nullable result, NSError *_Nullable error)
 Callback type for receiving place details lookups.
typedef void(^ GMSPlaceLikelihoodListCallback )(GMSPlaceLikelihoodList *_Nullable likelihoodList, NSError *_Nullable error)
 Callback type for receiving place likelihood lists.
typedef void(^ GMSPlaceLikelihoodsCallback )(NSArray< GMSPlaceLikelihood * > *_Nullable likelihoods, NSError *_Nullable error)
 Callback type for receiving array of GMSPlaceLikelihoods.
typedef void(^ GMSAutocompletePredictionsCallback )(NSArray< GMSAutocompletePrediction * > *_Nullable results, NSError *_Nullable error)
 Callback type for receiving autocompletion results.
typedef void(^ GMSPlacePhotoMetadataResultCallback )(GMSPlacePhotoMetadataList *_Nullable photos, NSError *_Nullable error)
 Callback type for receiving place photos results.
typedef void(^ GMSPlacePhotoImageResultCallback )(UIImage *_Nullable photo, NSError *_Nullable error)
 Callback type for receiving UIImage objects from a GMSPlacePhotoMetadata object.
typedef void(^ GMSPlaceOpenStatusCallback )(GMSPlaceOpenStatus result, NSError *_Nullable error)
 Callback type for receiving the opening hours status for the Place.
typedef void(^ GMSPlaceOpenStatusResponseCallback )(GMSPlaceIsOpenResponse *response, NSError *_Nullable error)
 Callback type for receiving the open status response.
typedef void(^ GMSPlaceSearchByTextResultCallback )(NSArray< GMSPlace * > *_Nullable places, NSError *_Nullable error)
 Callback type for receiving search by text results.
typedef void(^ GMSFetchPhotoResultCallback )(UIImage *_Nullable photoImage, NSError *_Nullable error)
 Callback type for receiving a photo.
typedef void(^ GMSAutocompleteSuggestionsCallback )(NSArray< GMSAutocompleteSuggestion * > *_Nullable results, NSError *_Nullable error)
 Callback type for autocomplete results.
typedef void(^ GMSPlaceSearchNearbyResultCallback )(NSArray< GMSPlace * > *_Nullable places, NSError *_Nullable error)
 Callback type for receiving search nearby results.

Member Function Documentation

+ (instancetype) sharedClient

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.

+ (BOOL) provideAPIKey: (NSString *)  key

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:).

Returns:
YES if the APIKey was successfully provided.
+ (NSString *) openSourceLicenseInfo

Returns the open source software license information for the Google Places SDK for iOS.

This information must be made available within your application.

+ (NSString *) SDKVersion

Returns the version for this release of the Google Places SDK for iOS.

. For example, "1.0.0".

+ (NSString *) SDKLongVersion

Returns the long version for this release of the Google Places SDK for iOS.

. For example, "1.0.0 (102.1)".

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

Get details for a place.

This method is non-blocking.

Parameters:
placeIDThe place ID to lookup.
callbackThe callback to invoke with the lookup result.
Note:
This is deprecated. This method is replaced by fetchPlaceWithRequest:callback: and will be removed in a future release.
- (void) fetchAutocompleteSuggestionsFromRequest: (GMSAutocompleteRequest *)  request
callback: (GMSAutocompleteSuggestionsCallback callback 

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.

Parameters:
requestThe GMSAutocompleteRequest request for autocomplete.
callbackThe callback to invoke with the suggestions.
- (void) lookUpPhotosForPlaceID: (NSString *)  placeID
callback: (GMSPlacePhotoMetadataResultCallback callback 

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.

Parameters:
placeIDThe place ID for which to lookup photos.
callbackThe callback to invoke with the lookup result.
- (void) loadPlacePhoto: (GMSPlacePhotoMetadata *)  photoMetadata
callback: (GMSPlacePhotoImageResultCallback callback 

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.

Parameters:
photoMetadataThe GMSPlacePhotoMetadata for which to load a UIImage.
callbackThe callback to invoke with the loaded UIImage.
- (void) loadPlacePhoto: (GMSPlacePhotoMetadata *)  photoMetadata
constrainedToSize: (CGSize)  maxSize
scale: (CGFloat)  scale
callback: (GMSPlacePhotoImageResultCallback callback 

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.
Parameters:
photoMetadataThe GMSPlacePhotoMetadata for which to load a UIImage.
maxSizeThe maximum size of the image.
scaleThe scale to load the image at.
callbackThe callback to invoke with the loaded UIImage.

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.
Parameters:
callbackThe callback to invoke with the place likelihood list.
- (void) findAutocompletePredictionsFromQuery: (NSString *)  query
filter: (nullable GMSAutocompleteFilter *)  filter
sessionToken: (nullable GMSAutocompleteSessionToken *)  sessionToken
callback: (GMSAutocompletePredictionsCallback callback 

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.

Parameters:
queryThe partial text to autocomplete.
filterThe filter to apply to the results. This parameter may be nil.
sessionTokenThe GMSAutocompleteSessionToken to associate request to a billing session.
callbackThe callback to invoke with the predictions.
- (void) fetchPlaceFromPlaceID: (NSString *)  placeID
placeFields: (GMSPlaceField placeFields
sessionToken: (nullable GMSAutocompleteSessionToken *)  sessionToken
callback: (GMSPlaceResultCallback callback 

Fetch details for a place.

This method is non-blocking.

Parameters:
placeIDThe place ID to lookup.
placeFieldsThe individual place fields requested for the place objects in the list.
sessionTokenThe GMSAutocompleteSessionToken to associate request to a billing session.
callbackThe callback to invoke with the lookup result.
Note:
This is deprecated. This method is replaced by fetchPlaceWithRequest:callback: callback: and will be removed in a future release.
- (void) findPlaceLikelihoodsFromCurrentLocationWithPlaceFields: (GMSPlaceField placeFields
callback: (GMSPlaceLikelihoodsCallback callback 

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.

Parameters:
placeFieldsThe individual place fields requested for the place objects in the list.
callbackThe callback to invoke with place likelihoods.
- (void) isOpenWithRequest: (GMSPlaceIsOpenRequest *)  isOpenRequest
callback: (GMSPlaceOpenStatusResponseCallback callback 

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

Parameters:
isOpenRequestThe request to determine the open status for a given place.
callbackThe callback to invoke with the open status response.
- (void) isOpenWithPlaceID: (NSString *)  placeID
callback: (GMSPlaceOpenStatusCallback callback 

Gets the open status for a place including all fields necessary to determine GMSPlaceOpenStatus at the current time.

This method is non-blocking.

Parameters:
placeIDThe place ID to lookup.
callbackThe callback to invoke with the place result.
- (void) isOpenWithPlaceID: (NSString *)  placeID
date: (NSDate *)  date
callback: (GMSPlaceOpenStatusCallback callback 

Gets the open status for a place including all fields necessary to determine GMSPlaceOpenStatus at the specified NSDate.

This method is non-blocking.

Parameters:
placeIDThe place ID to lookup.
dateThe NSDate to determine open status for.
callbackThe callback to invoke with the place result.
- (void) isOpenWithPlace: (GMSPlace *)  place
callback: (GMSPlaceOpenStatusCallback callback 

Gets the open status 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.

Parameters:
placeThe GMSPlace to lookup.
callbackThe callback to invoke with the place result.
- (void) isOpenWithPlace: (GMSPlace *)  place
date: (NSDate *)  date
callback: (GMSPlaceOpenStatusCallback callback 

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.

Parameters:
placeThe GMSPlace to lookup.
dateThe NSDate to determine open status for.
callbackThe callback to invoke with the place result.

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

Search for places by text and restrictions.

This method is non-blocking.

Parameters:
textSearchRequestGMSPlaceSearchByTextRequest The text request to use for the query.
callbackThe callback to invoke with the lookup result.
- (void) fetchPlaceWithRequest: (GMSFetchPlaceRequest *)  fetchPlaceRequest
callback: (GMSPlaceResultCallback callback 

Get a place using a request object.

This method is non-blocking.

Parameters:
fetchPlaceRequestGMSFetchPlaceRequest The fetch place request to use for the query.
callbackThe callback to invoke with the place result.
- (void) fetchPhotoWithRequest: (GMSFetchPhotoRequest *)  fetchPhotoRequest
callback: (GMSFetchPhotoResultCallback callback 

Request a photo using fetch photo request.

This method is non-blocking.

Parameters:
fetchPhotoRequestGMSFetchPhotoRequest The photo request to use.
callbackThe callback to invoke with the NSURL result.
- (void) searchNearbyWithRequest: (GMSPlaceSearchNearbyRequest *)  searchNearbyRequest
callback: (GMSPlaceSearchNearbyResultCallback callback 

Search for places near a location and restriction.

This method is non-blocking.

Parameters:
searchNearbyRequestGMSPlaceSearchNearbyRequest The search nearby request to use for the query.
callbackThe callback to invoke with the lookup result.

- (typedef void(^ GMSPlaceResultCallback)(GMSPlace *_Nullable result, NSError *_Nullable error)) [related]

Callback type for receiving place details lookups.

If an error occurred, result will be nil and error will contain information about the error.

Parameters:
resultThe GMSPlace that was returned.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlaceLikelihoodListCallback)(GMSPlaceLikelihoodList *_Nullable likelihoodList, NSError *_Nullable error)) [related]

Callback type for receiving place likelihood lists.

If an error occurred, likelihoodList will be nil and error will contain information about the error.

Parameters:
likelihoodListThe list of place likelihoods.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlaceLikelihoodsCallback)(NSArray< GMSPlaceLikelihood * > *_Nullable likelihoods, NSError *_Nullable error)) [related]

Callback type for receiving array of GMSPlaceLikelihoods.

If an error occurred, the array will be nil and error will contain information about the error.

- (typedef void(^ GMSAutocompletePredictionsCallback)(NSArray< GMSAutocompletePrediction * > *_Nullable results, NSError *_Nullable error)) [related]

Callback type for receiving autocompletion results.

results is an array of GMSAutocompletePredictions representing candidate completions of the query.

Parameters:
resultsAn array of GMSAutocompletePredictions.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlacePhotoMetadataResultCallback)(GMSPlacePhotoMetadataList *_Nullable photos, NSError *_Nullable error)) [related]

Callback type for receiving place photos results.

If an error occurred, photos will be nil and error will contain information about the error.

Parameters:
photosThe result containing GMSPlacePhotoMetadata objects.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlacePhotoImageResultCallback)(UIImage *_Nullable photo, NSError *_Nullable error)) [related]

Callback type for receiving UIImage objects from a GMSPlacePhotoMetadata object.

If an error occurred, photo will be nil and error will contain information about the error.

Parameters:
photoThe UIImage which was loaded.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlaceOpenStatusCallback)(GMSPlaceOpenStatus result, NSError *_Nullable error)) [related]

Callback type for receiving the opening hours status for the Place.

If an error occurred, result will be GMSPlaceOpenStatusUnknown and error will contain information about the error.

Parameters:
resultThe GMSPlaceOpenStatus that was returned.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlaceOpenStatusResponseCallback)(GMSPlaceIsOpenResponse *response, NSError *_Nullable error)) [related]

Callback type for receiving the open status response.

If an error occurred, response will be have a status of GMSPlaceOpenStatusUnknown and error will contain information about the error.

Parameters:
responseThe GMSPlaceIsOpenResponse that was returned.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlaceSearchByTextResultCallback)(NSArray< GMSPlace * > *_Nullable places, NSError *_Nullable error)) [related]

Callback type for receiving search by text results.

results is an array of GMSPlace representing individual results matching the query.

Parameters:
resultsAn array of GMSPlaces.
errorThe error that occurred, if any.
- (typedef void(^ GMSFetchPhotoResultCallback)(UIImage *_Nullable photoImage, NSError *_Nullable error)) [related]

Callback type for receiving a photo.

photoImage is a UIImage representing the resulting photo matching the specified request. If an error occurred, photoImage will be nil and error will contain information about the error.

Parameters:
photoImageA UIImage result.
- (typedef void(^ GMSAutocompleteSuggestionsCallback)(NSArray< GMSAutocompleteSuggestion * > *_Nullable results, NSError *_Nullable error)) [related]

Callback type for autocomplete results.

Parameters:
resultsAn array of GMSAutocompleteSuggestion.
errorThe error that occurred, if any.
- (typedef void(^ GMSPlaceSearchNearbyResultCallback)(NSArray< GMSPlace * > *_Nullable places, NSError *_Nullable error)) [related]

Callback type for receiving search nearby results.

Parameters:
placesAn array of GMSPlace
errorThe error that occurred, if any.