文本搜索会根据字符串返回一组地点的相关信息。例如,“北京烤鸭”“南京附近的鞋店”或“长安街 123 号”。该服务会返回一个与文本字符串和任何设置的位置偏差匹配的地点列表。
该服务对于在自动化系统中进行模糊地址查询特别有用,并且字符串的非地址组成部分可以与商家以及地址匹配。模糊地址查询示例包括格式不佳的地址或包含非地址组成部分(如商家名称)的请求。除非设置了位置(例如地区、位置限制或位置偏向),否则前两个示例这样的请求可能不会返回任何结果。
“10 High Street, UK”或“123 Main Street, US” | 英国有多个“High Street”;美国有多个“Main Street”。 除非设置了位置限制,否则查询不会返回所需的结果。 |
“纽约连锁餐厅” | 纽约有多个“连锁餐厅”营业地点;没有街道地址,甚至没有街道名称。 |
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” | 只有一条位于英国埃舍尔市的“高街”;在美国加利福尼亚州普莱森顿市只有一条“主街”。 |
“纽约 UniqueRestaurantName” | 在纽约只有一家使用此名称的场所;无需使用街道地址进行区分。 |
“北京烤鸭店” | 此查询包含其位置限制,“北京烤鸭”是一种定义明确的地点类型。它会返回多个结果。 |
“+1 514-670-8700” | 此查询包含电话号码。它会返回与该电话号码关联的地点的多个结果。 |
通过文本搜索获取地点列表
Places SDK for iOS(新)中的文本搜索请求采用以下格式:
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);
}
必需参数
-
字段列表
指定要返回的地点数据属性。传递
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
、GMSPlacePropertyServesBeer
、GMSPlacePropertyServesBreakfast
、GMSPlacePropertyServesBrunch
、GMSPlacePropertyServesDinner
、GMSPlacePropertyServesLunch
、GMSPlacePropertyServesVegetarianFood
、GMSPlacePropertyServesWine
、GMSPlacePropertyTakeout
-
textQuery
要搜索的文本字符串,例如:“餐馆”、“主街 123 号”或“旧金山最佳去处”。
可选参数
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(默认值)之间,包括 1 和 20。
minRating
将结果限制为平均用户评分大于或等于此上限的结果。值必须介于 0.0 和 5.0 之间(含 0.0 和 5.0),以 0.5 为增量。例如:0、0.5、1.0、...、5.0(含 0 和 5.0)。值会四舍五入到最接近的 0.5。例如,值为 0.6 会排除评分低于 1.0 的所有结果。
-
priceLevels
将搜索范围限制为特定价位的地点。 默认设置是选择所有价位。
指定一个数组,其中包含由
PriceLevel
定义的一个或多个值。例如:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
指定结果在响应中的排名方式。在适用的情况下,该 API 默认使用
RELEVANCE
。例如,对于“纽约市餐厅”之类的查询,系统将使用默认值RELEVANCE
。对于地理位置查询(例如“加利福尼亚州山景城”)或其他类型的查询,系统不会应用任何默认值,并且结果会按照后端返回的顺序显示。相关的值包括:
.distance
:按距离对结果排名。.relevance
:按相关性对结果排名。
regionCode
用于设置响应格式的地区代码,以 双字符 CLDR 代码值的形式指定。此参数也会对搜索结果产生偏差影响。没有默认值。
如果响应中地址字段的国家/地区名称与地区代码匹配,则地址中省略国家/地区代码。
除了某些明显的例外情况之外,大多数 CLDR 代码都与 ISO 3166-1 代码相同。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(专指“大不列颠及北爱尔兰联合王国”)。 该参数可能会影响根据适用法律的结果。
“文本搜索”响应
Text Search API 以 GMSPlace
对象的形式返回匹配项数组,每个匹配地点有一个 GMSPlace
对象。