A Text Search returns information about a set of places based on a string. For example, "pizza in New York", "shoe stores near Ottawa", or "123 Main Street". The service responds with a list of places matching the text string and any set location bias.
The service is especially useful for making ambiguous address queries in an automated system, and non-address components of the string may match businesses as well as addresses. Examples of ambiguous address queries are poorly-formatted addresses or requests that include non-address components, such as business names. Requests like the first two examples might return zero results unless a location (such as region, location restriction, or location bias) is set.
"10 High Street, UK" or "123 Main Street, US" | Multiple "High Street"s in the UK; multiple "Main Street"s in the US. Query doesn't return desirable results unless a location restriction is set. |
"Chain restaurant New York" | Multiple "Chain restaurant" locations in New York; no street address or even street name. |
"10 High Street, Escher UK" or "123 Main Street, Pleasanton US" | Only one "High Street" in the UK city of Escher; only one "Main Street" in the US city of Pleasanton CA. |
"UniqueRestaurantName New York" | Only one establishment with this name in New York; no street address needed to differentiate. |
"pizza restaurants in New York" | This query contains its location restriction, and "pizza restaurants" is a well-defined place type. It returns multiple results. |
"+1 514-670-8700" | This query contains a phone number. It returns multiple results for places associated with that phone number. |
Get a list of places by text search
A Text Search request in the Places SDK for iOS (New) follows the form:
Swift
func testPlaceSearchByTextRequestGMPSRequestCreationWithProperties() {
let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID];
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
request.locationRestriction = GMSPlaceRectangularLocationOption(
CLLocationCoordinate2D(latitude: 20, longitude: 30),
CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
}
Objective-C
- (void)testPlaceSearchByTextRequestGMPSRequestCreationWithProperties {
GMSPlaceSearchByTextRequest *request =
[[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationRestriction = GMSPlaceRectangularLocationOption(
CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50));
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0);
}
Required parameters
-
Field list
Specify which place data properties to return. Pass a list of
GMSPlace
properties specifying the data fields to return. If you omit the field mask, the request will return an error.Field lists are 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 Text Search (ID Only) SKU:
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
The following fields trigger the Text Search (Basic) SKU:
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
,GMSPlacePropertyWheelchairAccessibleEntrance
The following fields trigger the Text Search (Advanced) SKU:
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
The following fields trigger the Text Search (Preferred) SKU:
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
,GMSPlacePropertyTakeout
-
textQuery
The text string on which to search, for example: "restaurant", "123 Main Street", or "best place to visit in San Francisco".
Optional parameters
includedType
Restricts the results to places matching the specified type defined by Table A. Only one type may be specified. For example:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
If
true
, return only those places that are open for business at the time the query is sent. Iffalse
, return all businesses regardless of open status. Places that don't specify opening hours in the Google Places database are returned if you set this parameter tofalse
.isStrictTypeFiltering
Used with the
includeType
parameter. When set totrue
, only places that match the specified types specified byincludeType
are returned. When false, the default, the response can contain places that don't match the specified types.locationBias
Specifies an area to search. This location serves as a bias which means results around the specified location can be returned, including results outside the specified area.
You can specify
locationRestriction
orlocationBias
, but not both. Think oflocationRestriction
as specifying the region which the results must be within, andlocationBias
as specifying the region that the results must be near but can be outside of the area.Specify the region as a rectangular Viewport or as a circle.
A circle is 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. For example:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
A rectangle is a latitude-longitude viewport, represented as two diagonally opposite low and high points. The low point marks the southwest corner of the rectangle, and the high point represents the northeast corner of the rectangle.
A viewport is considered a closed region, meaning it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive:
- If
low
=high
, the viewport consists of that single point. - If
low.longitude
>high.longitude
, the longitude range is inverted (the viewport crosses the 180 degree longitude line). - If
low.longitude
= -180 degrees andhigh.longitude
= 180 degrees, the viewport includes all longitudes. - If
low.longitude
= 180 degrees andhigh.longitude
= -180 degrees, the longitude range is empty. - If
low.latitude
>high.latitude
, the latitude range is empty.
- If
locationRestriction
Specifies an area to search. Results outside the specified area are not returned. Specify the region as a rectangular Viewport. See the description of
locationBias
for information on defining the Viewport.You can specify
locationRestriction
orlocationBias
, but not both. Think oflocationRestriction
as specifying the region which the results must be within, andlocationBias
as specifying the region that the results must be near but can be outside of the area.-
maxResultCount
Specifies the maximum number of place results to return. Must be between 1 and 20 (default) inclusive.
minRating
Restricts results to only those whose average user rating is greater than or equal to this limit. Values must be between 0.0 and 5.0 (inclusive) in increments of 0.5. For example: 0, 0.5, 1.0, ... , 5.0 inclusive. Values are rounded up to the nearest 0.5. For example, a value of 0.6 eliminates all results with a rating less than 1.0.
-
priceLevels
Restrict the search to places that are marked at certain price levels. The default is to select all price levels.
Specify an array of one or more of values defined by
PriceLevel
.For example:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
Specifies how the results are ranked in the response. The API uses
RELEVANCE
by default when applicable. For example, for a query such as "Restaurants in New York City" thenRELEVANCE
is the default. For geographical queries, such as "Mountain View, CA", or other type of queries then no default is applied and the results appear in the order that they are returned by the backend.Values include:
.distance
: Rank results by distance..relevance
: Rank results by relevance.
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.
Text Search responses
The Text Search API returns an array of matches in the
form of
GMSPlace
objects, with one GMSPlace
object per matching place.