文本搜索会返回一组地点的相关信息 字符串。例如,“北京烤鸭”、“附近的鞋店” 或“长安街 123 号”。该服务会返回地点列表 匹配文本字符串和任何已设置的位置偏向。
该服务特别适合用于使地址模糊不清的地址 查询。 和非地址部分可以匹配商家以及 地址。模糊地址查询示例是格式不正确的地址 或包含非地址组成部分(例如商家名称)的请求。 与前两个示例类似的请求可能返回零结果,除非 位置(如区域、位置限制或位置偏向)设置。
“英国,高街 10 号”或“123 Main Street, US” | 英国的多个“高街”;美国的多条“主街” 除非位置限制是 。 |
“纽约连锁餐馆” | 多个“连锁餐厅”位于纽约的分店;无街道地址或 甚至街道名称。 |
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” | 仅一条“高街”英国埃舍尔市;只有一个“Main Street” 位于美国加利福尼亚州普莱森顿 |
“UniqueRestaurantName New York” | 纽约只有一个具有此名称的场所;无街道地址 进行区分 |
“北京烤鸭店” | 此查询包含其位置限制以及“北京烤鸭店”为 明确定义的地点类型该方法会返回多个结果。 |
“+1 514-670-8700” | 此查询包含电话号码。它会针对以下查询返回多个结果: 显示与该电话号码相关的地点 |
通过文本搜索获取地点列表
通过调用 GMSPlacesClient
searchByTextWithRequest:
发出“文本搜索”请求。
通过一个
GMSPlaceSearchByTextRequest
对象,该对象定义了请求参数和回调方法,其类型为
GMSPlaceSearchByTextResultCallback
,
处理响应。
GMSPlaceSearchByTextRequest
对象指定
必需参数和可选参数
。必需的参数包括:
GMSPlace
对象中要返回的字段列表, 称为字段掩码,如GMSPlaceProperty
。 您未在字段列表中指定至少一个字段,或者省略了 字段列表,则该调用会返回错误。- 文本查询。
此示例文本搜索请求指定响应 GMSPlace
对象
包含搜索中每个 GMSPlace
对象的地点名称和地点 ID
结果。它还会过滤响应,以仅返回以下类型的地点:
“餐馆”。
Swift
// Create the GMSPlaceSearchByTextRequest object. let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue} let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0) // Array to hold the places in the response var placeResults: [GMSPlace] = [] 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 } placeResults = results } GMSPlacesClient.shared().searchByText(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.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { 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
对象。
获取营业状态
GMSPlacesClient
对象包含一个名为 isOpenWithRequest
(在 Swift 中为 isOpenRequest
,在 GooglePlacesSwift 中为 isPlaceOpenRequest
)的成员函数,该函数会根据在调用中指定的时间,返回指示该地点当前是否营业的响应。
此方法接受 GMSPlaceIsOpenWithRequest
类型的单个参数,其中包含:
GMSPlace
对象,或用于指定地点 ID 的字符串。如需详细了解如何使用必填字段创建 Place 对象,请参阅地点详情。
- 可选的
NSDate
(Obj-C) 或Date
(Swift) 对象,用于指定您想要检查的时间。如果未指定时间,则默认值为现在。 - 用于处理响应的
GMSPlaceOpenStatusResponseCallback
方法。
GMSPlaceIsOpenWithRequest
方法要求在 GMSPlace
对象中设置以下字段:
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyBusinessStatus
GMSPlacePropertyOpeningHours
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
如果地点对象中未提供这些字段,或者您传递了地点 ID,该方法会使用 GMSPlacesClient GMSFetchPlaceRequest:
进行提取。
isOpenWithRequest
响应
isOpenWithRequest
会返回一个包含名为 status
的布尔值的 GMSPlaceIsOpenResponse
对象,此值用于指明商家是处于营业状态、已停业还是未知。
语言 | 营业时的值 | 停业时的值 | 状态未知时的值 |
---|---|---|---|
Swift | .open |
.closed |
.unknown |
Objective-C | GMSPlaceOpenStatusOpen |
GMSPlaceOpenStatusClosed |
GMSPlaceOpenStatusUnknown |
GooglePlacesSwift(预览版) | true |
false |
nil |
“isOpenWithRequest
”的结算
GMSPlacePropertyUTCOffsetMinutes
和GMSPlacePropertyBusinessStatus
字段按基本数据 SKU 计费。其余营业时间在地点详情(高级)SKU 下计费。- 如果您的
GMSPlace
对象已包含上一个请求中的这些字段,系统将不会再向您收费。
示例:发出 GMSPlaceIsOpenWithRequest
请求
以下示例展示了如何在现有的 GMSPlace
对象中初始化 GMSPlaceIsOpenWithRequest
。
Swift
let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil) GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in if let error = error { // Handle Error } switch response.status { case .open: // Handle open case .closed: // Handle closed case .unknown: // Handle unknown } }
Objective-C
GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil]; [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) { if (error) { // Handle error } switch (response.status) { case GMSPlaceOpenStatusOpen: // Handle open case GMSPlaceOpenStatusClosed: // Handle closed case GMSPlaceOpenStatusUnknown: // Handle unknown } }];
GooglePlacesSwift
let isOpenRequest = IsPlaceOpenRequest(place: place) switch await placesClient.isPlaceOpen(with: isOpenRequest) { case .success(let isOpenResponse): switch isOpenResponse.status { case true: // Handle open case false: // Handle closed case nil: // Handle unknown case .failure(let placesError): // Handle error }
必需参数
使用 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 Main” 或“旧金山最佳游览地点”。
可选参数
使用 GMSPlaceSearchByTextRequest
对象指定可选的
参数。
includedType
将结果限制为与 定义的指定类型相匹配的地点。 表 A. 只能指定一个类型。例如:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
如果为
true
,则仅返回正常营业的地点 。如果为false
,则返回所有商家 而无论打开状态如何 未在 Google Places 数据库中指定营业时间的地点为 返回false
。isStrictTypeFiltering
与
includeType
参数搭配使用。设置为true
,则仅搜索与由 返回includeType
。 如果为 false(默认值),响应可以包含不匹配的地点 指定的类型。locationBias
指定要搜索的区域。这个位置就是一种偏差,这意味着 可返回指定位置周围的结果,包括结果 在指定区域之外。
您可以指定
locationRestriction
或locationBias
, 但不能同时设置这两者。可以将locationRestriction
视为指定 结果所在的区域,以及locationBias
指定结果必须靠近但可以不在的区域 数据。将区域指定为矩形视口或圆形。
圆形由中心点和半径(以米为单位)定义。半径 必须介于 0.0 和 50000.0 之间(含 0.0 和 50000.0)。默认半径为 0.0。 例如:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)
矩形是一种经纬度视口,表示为 低点和高点对角线。低点表示西南方 矩形的一角,高点表示东北 矩形的一角。
视口被视为 表示它包含其边界。纬度边界 必须介于 -90 度(含)到 90 度(含)之间,且经度范围必须为 必须介于 -180 度到 180 度之间(包括 -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(默认值),包括 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
指定如何根据 查询:
- 对于像“Restaurants in New York City”这样的分类查询,
默认值为
.relevance
(按搜索相关性对结果排名)。 您可以将rankPreference
设置为.relevance
或.distance
(按距离对结果排名)。 - 对于非分类查询(例如“Mountain View, CA”),我们建议
让
rankPreference
保持未设置状态。
- 对于像“Restaurants in New York City”这样的分类查询,
默认值为
regionCode
用于设置响应格式的地区代码,指定为 两个字符的 CLDR 代码值。此参数也可能具有偏差效应 。没有默认值。
如果响应中地址字段的国家/地区名称与 区号,则地址中省略了国家/地区代码。
大多数 CLDR 代码与 ISO 3166-1 代码相同, 但有一些值得注意的例外情况。例如,英国的 ccTLD 为 "uk"(.co.uk),而其 ISO 3166-1 代码为“gb”(从技术层面来讲, “大不列颠及北爱尔兰联合王国”)。 根据适用法律,该参数可能会影响结果。
在应用中显示提供方说明
当应用显示从
GMSPlacesClient
,
如照片和评价,则应用还必须显示必要的提供方说明。
例如,GMSPlacesClient
对象的 reviews
属性
包含一个数组,该数组最多包含五个
GMSPlaceReview
对象的操作。每个 GMSPlaceReview
对象都可以包含提供方说明和作者提供方说明。
如果您要在应用中显示评价,则还必须显示出处或作者
归因。
有关详情,请参阅 归因。