文本搜索会根据字符串返回一组地点的相关信息。例如,“北京烤鸭”“南京附近的鞋店”或“长安街 123 号”。该服务会返回与文本字符串和任何已设置的位置偏差相匹配的地点列表。
该服务特别适合在自动化系统中进行地址模糊查询,字符串的非地址组成部分可能与商家以及地址匹配。模糊地址查询的示例包括格式不正确的地址,或包含非地址组成部分(例如商家名称)的请求。除非设置了位置(例如地区、位置限制或位置偏向),否则与前两个示例类似的请求可能返回零结果。
“10 High Street, UK”或“123 Main Street, US” | 英国有多个“高街”;美国有多条“主街”。 除非设置了位置限制,否则查询不会返回所需的结果。 |
“纽约连锁餐馆” | 纽约的多个“连锁餐厅”营业地点;没有街道地址,甚至没有街道名称。 |
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” | 英国埃舍尔市只有一条“高街”;在美国加利福尼亚州普莱森顿市只有一条“主街”。 |
“UniqueRestaurantName New York” | 在纽约只有一个具有此名称的场所;无需区分街道地址。 |
“北京烤鸭店” | 此查询包含其位置限制,“北京烤鸭”是一种明确定义的地点类型。该方法会返回多个结果。 |
“+1 514-670-8700” | 此查询包含电话号码。它会针对与该电话号码关联的地点返回多个结果。 |
通过文本搜索获取地点列表
要发出“文本搜索”请求,请调用 GMSPlacesClient
searchByTextWithRequest:
,并传递用于定义请求参数的 GMSPlaceSearchByTextRequest
对象以及用于处理响应的 GMSPlaceSearchByTextResultCallback
类型的回调方法。
GMSPlaceSearchByTextRequest
对象指定请求的所有必需和可选参数。必需的参数包括:
GMSPlace
对象中要返回的字段列表(也称为字段掩码,由GMSPlaceProperty
定义)。 如果您未在字段列表中指定至少一个字段,或省略字段列表,则调用将返回错误。- 文本查询。
此示例文本搜索请求指定,响应 GMSPlace
对象包含搜索结果中每个 GMSPlace
对象的地点名称和地点 ID。它还过滤响应,仅返回“餐馆”类型的地点。
Swift
// Create the GMSPlaceSearchByTextRequest object. 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) ) // Array to hold the places in the response placeResults = []; let callback: GMSPlaceSearchByTextResultCallback = { [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 } self.placeResults = results } GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)
Objective-C
// Create the GMSPlaceSearchByTextRequest object. 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); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } }];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
文本搜索响应
Text Search API 以 GMSPlace
对象的形式返回匹配项数组,每个匹配地点对应一个 GMSPlace
对象。
除了数据字段之外,响应中的 GMSPlace
对象还包含以下成员函数:
-
isOpen
用于计算地点在给定时间是否营业。 isOpenAtDate
用于计算地点在给定日期是否营业。
必需参数
使用 GMSPlaceSearchByTextRequest
对象指定搜索的必需参数。
-
字段列表
指定要返回的地点数据属性。传递
GMSPlace
属性列表,指定要返回的数据字段。如果您省略字段掩码,请求将返回错误。字段列表是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和结算费用。
指定以下一个或多个字段:
以下字段会触发文本搜索(仅 ID)SKU:
GMSPlacePropertyPlaceID
、GMSPlacePropertyName
以下字段会触发文本搜索(基本)SKU:
GMSPlacePropertyAddressComponents
、GMSPlacePropertyBusinessStatus
、GMSPlacePropertyFormattedAddress
、GMSPlacePropertyIconBackgroundColor
、GMSPlacePropertyIconImageURL
、GMSPlacePropertyCoordinate
、GMSPlacePropertyPhotos
、GMSPlacePropertyPlusCode
、GMSPlacePropertyTypes
、GMSPlacePropertyUTCOffsetMinutes
、GMSPlacePropertyViewport
、GMSPlacePropertyWheelchairAccessibleEntrance
以下字段会触发文本搜索(高级)SKU:
GMSPlacePropertyCurrentOpeningHours
、GMSPlacePropertySecondaryOpeningHours
、GMSPlacePropertyPhoneNumber
、GMSPlacePropertyPriceLevel
、GMSPlacePropertyRating
、GMSPlacePropertyOpeningHours
、GMSPlacePropertyUserRatingsTotal
、GMSPlacePropertyWebsite
以下字段会触发文本搜索(首选)SKU:
GMSPlacePropertyCurbsidePickup
、GMSPlacePropertyDelivery
、GMSPlacePropertyDineIn
、GMSPlacePropertyEditorialSummary
、GMSPlacePropertyReservable
、GMSPlacePropertyReviews
、GMSPlacePropertyServesBeer
、GMSPlacePropertyServesBreakfast
、GMSPlacePropertyServesBrunch
、GMSPlacePropertyServesDinner
、GMSPlacePropertyServesLunch
、GMSPlacePropertyServesVegetarianFood
、GMSPlacePropertyServesWine
、GMSPlacePropertyTakeout
-
textQuery
要搜索的文本字符串,例如“餐馆”“主街 123 号”或“旧金山的最佳去处”。
可选参数
使用 GMSPlaceSearchByTextRequest
对象指定搜索的可选参数。
includedType
将结果限制为与表 A 定义的指定类型相匹配的地点。只能指定一个类型。例如:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
如果为
true
,则仅返回发送查询时正在营业的地点。如果为false
,则返回所有商家,无论其是否处于营业状态。如果您将此参数设置为false
,则系统会返回未在 Google 地点数据库中指定营业时间的地点。isStrictTypeFiltering
与
includeType
参数搭配使用。设置为true
时,系统仅返回与includeType
指定的指定类型相匹配的地点。 如果为 false(默认值),响应可以包含与指定类型不匹配的地点。locationBias
指定要搜索的区域。此位置可充当偏差,这意味着可返回指定位置周围的结果,包括指定区域以外的结果。
您可以指定
locationRestriction
或locationBias
,但不能同时指定这两者。您可将locationRestriction
视为指定结果必须位于哪个区域,将locationBias
视为指定结果必须靠近但可位于该区域之外的区域。将区域指定为矩形视口或圆形。
圆形由中心点和半径(以米为单位)定义。半径必须介于 0.0 和 50000.0 之间(含 0.0 和 50000.0)。默认半径为 0.0。 例如:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
矩形是一种纬度-经度视口,表示为两个对角线相对的低点和高点。低点表示矩形的西南角,高点表示矩形的东北角。
视口被视为封闭区域,也就是说,视口包含其边界。纬度边界必须介于 -90 度和 90 度(含)之间,经度边界必须介于 -180 度和 180 度(含)之间:
- 如果
low
=high
,视口由该单点组成。 - 如果
low.longitude
>high.longitude
,则经度范围会反转(视口与 180 度经度线相交)。 - 如果
low.longitude
= -180 度且high.longitude
= 180 度,视口将包含所有经度。 - 如果
low.longitude
= 180 度且high.longitude
= -180 度,则经度范围为空。 - 如果
low.latitude
>high.latitude
,则纬度范围为空。
- 如果
locationRestriction
指定要搜索的区域。指定区域以外的结果不会返回。将区域指定为矩形视口。如需了解如何定义视口,请参阅
locationBias
的说明。您可以指定
locationRestriction
或locationBias
,但不能同时指定这两者。您可将locationRestriction
视为指定结果必须位于哪个区域,将locationBias
视为指定结果必须靠近但可位于该区域之外的区域。-
maxResultCount
指定要返回的地点结果的数量上限。必须介于 1 到 20(默认值)之间(包括这两个数值)。
minRating
将结果限制为平均用户评分大于或等于此限制的结果。值必须介于 0.0 和 5.0(含)之间,以 0.5 为增量。例如:0、0.5、1.0、...、5.0(含边界值)。值会四舍五入到最接近的 0.5。例如,值为 0.6 会排除评分低于 1.0 的所有结果。
-
priceLevels
将搜索范围限制为标记在特定价位的地点。默认设置是选择所有价位。
指定由
PriceLevel
定义的一个或多个值的数组。例如:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
指定如何基于查询类型在响应中对结果进行排名:
- 对于“纽约市的餐馆”等分类查询,
.relevance
(按搜索相关性对结果排名)是默认值。您可以将rankPreference
设置为.relevance
或.distance
(按距离对结果排序)。 - 对于非分类查询(例如“Mountain View, CA”),我们建议您不设置
rankPreference
。
- 对于“纽约市的餐馆”等分类查询,
regionCode
用于设置响应格式的地区代码,以 双字符 CLDR 代码值的形式指定。此参数还会对搜索结果产生偏差影响。没有默认值。
如果响应中地址字段的国家/地区名称与地区代码匹配,则地址中省略国家/地区代码。
大多数 CLDR 代码与 ISO 3166-1 代码相同,但也有一些值得注意的例外情况。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(特指“大不列颠及北爱尔兰联合王国”)。 根据适用法律,该参数可能会影响结果。
在应用中显示提供方说明
如果您的应用要显示从 GMSPlacesClient
获取的信息(例如照片和评价),则还必须显示必需的提供方说明。
例如,GMSPlacesClient
对象的 reviews
属性包含一个最多包含五个 GMSPlaceReview
对象的数组。每个 GMSPlaceReview
对象都可以包含提供方说明和作者提供方说明。如果您在应用中显示评价,则还必须显示提供方说明或作者提供方说明。
如需了解详情,请参阅有关归因的文档。