A Nearby Search (New) request takes as input the region to search
specified as a circle, defined by the latitude and longitude coordinates of the center point of the
circle and the radius in meters. The request returns a list of matching places, each represented by a
GMSPlace
object, within the specified search area.
By default, the response contains places of all types within the search area. You can optionally filter the response by specifying a list of place types to explicitly include in or exclude from the response. For example, you can specify to include only those places in the response that are of type "restaurant", "bakery", and "cafe", or exclude all places of type "school".
Nearby Search (New) requests
Make a Nearby Search request by calling
GMSPlacesClient searchNearbyWithRequest:
,
passing a
GMSPlaceSearchNearbyRequest
object that defines the request parameters and a callback method, of type
GMSPlaceSearchNearbyResultCallback
,
to handle the response.
The GMSPlaceSearchNearbyRequest
object specifies all of the
required and optional
parameters for the request. The required parameters include:
- The list of fields to return in the
GMSPlace
object, also called the field mask, as defined byGMSPlaceProperty
. 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. - The location restriction, meaning the circle defining the search area.
This example nearby search request specifies that the response GMSPlace
objects
contain the place name (GMSPlacePropertyName
) and place coordinates
(GMSPlacePropertyCoordinate
) for each GMSPlace
object in the search
results. It also filters the response to only return places of type "restaurant" and "cafe".
Swift
// Array to hold the places in the response var placeResults: [GMSPlace] = [] // Define the search area as a 500 meter diameter circle in San Francisco, CA. let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500) // Specify the fields to return in the GMSPlace object for each place in the response. let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue} // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties) let includedTypes = ["restaurant", "cafe"] request.includedTypes = includedTypes let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } placeResults = results } GMSPlacesClient.shared().searchNearby(with: request, callback: callback)
Objective-C
// Array to hold the places in the response _placeResults = [NSArray array]; // Define the search area as a 500 meter diameter circle in San Francisco, CA. id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500); // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc] initWithLocationRestriction:circularLocation placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]]; // Set the place types to filter on. NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ]; request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes]; [_placesClient searchNearbyWithRequest:request callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { // Get list of places. _placeResults = places; } } ];
GooglePlacesSwift
let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500) let searchNearbyRequest = SearchNearbyRequest( locationRestriction: restriction, placeProperties: [ .name, .coordinate], includedTypes: [ .restaurant, .cafe ], ) switch await placesClient.searchNearby(with: searchNearbyRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Nearby Search responses
The Nearby Search API returns an array of matches in the form ofGMSPlace
objects, with one GMSPlace
object per matching place.
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 GMSPlaceSearchNearbyRequest
object to specify the required parameters for
the search.
-
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 fromGMSPlaceProperty
to theGMSPlaceSearchNearbyRequest
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 Nearby Search (Basic) SKU:
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyCoordinate
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyName
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlaceID
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
,GMSPlacePropertyWheelchairAccessibleEntrance
The following fields trigger the Nearby Search (Advanced) SKU:
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
The following fields trigger the Nearby Search (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 thename
andplaceID
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];
GooglePlacesSwift
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
-
locationRestriction
A
GMSPlaceLocationRestriction
object that defines the region to search specified as a circle, defined by center point and radius in meters. The radius must be between 0.0 and 50000.0, inclusive. The default radius is 0.0. You must set it in your request to a value greater than 0.0.
Optional parameters
Use the GMSPlaceSearchNearbyRequest
object to specify the optional parameters for
the search.
-
includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes
Lets you specify a list of types from types Table A used to filter the search results. Up to 50 types can be specified in each type restriction category.
A place can only have a single primary type from types Table A associated with it. For example, the primary type might be
"mexican_restaurant"
or"steak_house"
. UseincludedPrimaryTypes
andexcludedPrimaryTypes
to filter the results on a place's primary type.A place can also have multiple type values from types Table A associated with it. For example a restaurant might have the following types:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. UseincludedTypes
andexcludedTypes
to filter the results on the list of types associated with a place.If a search is specified with multiple type restrictions, only places that satisfy all of the restrictions are returned. For example, if you specify
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, the returned places provide"restaurant"
related services but don't operate primarily as a"steak_house"
.includedTypes
A list of the place types from Table A to search for. If this parameter is omitted, places of all types are returned.
excludedTypes
A list of place types from Table A to exclude from a search.
If you specify both the
includedTypes
(such as"school"
) and theexcludedTypes
(such as"primary_school"
) in the request, then the response includes places that are categorized as"school"
but not as"primary_school"
. The response includes places that match at least one of theincludedTypes
and none of theexcludedTypes
.If there are any conflicting types, such as a type appearing in both
includedTypes
andexcludedTypes
, anINVALID_REQUEST
error is returned.includedPrimaryTypes
A list of primary place types from Table A to include in a search.
excludedPrimaryTypes
A list of primary place types from Table A to exclude from a search.
If there are any conflicting primary types, such as a type appearing in both
includedPrimaryTypes
andexcludedPrimaryTypes
, anINVALID_ARGUMENT
error is returned. -
maxResultCount
Specifies the maximum number of place results to return. Must be between 1 and 20 (default) inclusive.
-
rankPreference
The type of ranking to use. If this parameter is omitted, results are ranked by popularity. May be one of the following:
.popularity
(default) Sorts results based on their popularity..distance
Sorts results in ascending order by their distance from the specified location.
-
regionCode
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
formattedAddress
field in the response matches theregionCode
, the country code is omitted fromformattedAddress
. This parameter has no effect onadrFormatAddress
, which always includes the country name, or onshortFormattedAddress
, which never includes it.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.
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.