文本搜索(新)会根据一个字符串(例如,“北京烤鸭”“南京附近的鞋店”或“长安街 8 号”)返回一组地点的相关信息。该服务会返回一个与文本字符串和任何位置偏向设置相匹配的地点列表。
该服务对于在自动化系统中进行模糊地址查询特别有用,并且字符串的非地址组成部分可以与商家以及地址匹配。模糊地址查询的示例包括格式错误的地址,或包含商家名称等非地址组成部分的请求。除非设置了地理位置(例如地区、位置限制或位置偏向),否则下表中的前两个示例等请求可能会返回零结果。
“10 High Street, UK”或“123 Main Street, US” | 英国有多个“High Street”;美国有多个“Main Street”。 除非设置了位置限制,否则查询不会返回所需的结果。 |
“纽约连锁餐厅” | 纽约有多个“ChainRestaurant”分店;没有街道地址,甚至没有街道名称。 |
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” | 只有一条位于英国埃舍尔市的“高街”;在美国加利福尼亚州普莱森顿市只有一条“主街”。 |
“纽约 UniqueRestaurantName” | 在纽约只有一家使用此名称的场所;无需使用街道地址进行区分。 |
“北京烤鸭店” | 此查询包含其位置限制,“北京烤鸭”是一种定义明确的地点类型。它会返回多个结果。 |
“+1 514-670-8700” | 此查询包含电话号码。它会返回与该电话号码关联的地点的多个结果。 |
借助 API Explorer,您可以发出实时请求,以便熟悉 API 和 API 选项:
“文本搜索”请求
“文本搜索”请求是一个 HTTP POST 请求,其格式如下:
https://places.googleapis.com/v1/places:searchText
将 JSON 请求正文或标头中的所有参数作为 POST 请求的一部分传递。例如:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
文本搜索(新)响应
文本搜索(新)会返回 JSON 对象作为响应。在响应中:
places
数组包含所有匹配的地点。- 数组中的每个地点均由一个
Place
对象表示。Place
对象包含单个地点的详细信息。 - 请求中传递的 FieldMask 指定
Place
对象中返回的字段列表。
完整的 JSON 对象采用以下格式:
{ "places": [ { object (Place) } ] }
必需参数
-
FieldMask
通过创建响应字段掩码,指定要在响应中返回的字段列表。使用网址参数
$fields
或fields
,或者使用 HTTP 标头X-Goog-FieldMask
将响应字段掩码传递给该方法。响应中没有默认的返回字段列表。 如果省略字段掩码,则该方法会返回错误。字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和结算费用。
指定要返回的地点数据类型的逗号分隔列表。例如,用于检索地点的显示名称和地址。
X-Goog-FieldMask: places.displayName,places.formattedAddress
使用
*
检索所有字段。X-Goog-FieldMask: *
指定以下一个或多个字段:
以下字段会触发文本搜索(仅 ID)SKU:
places.id
、places.name
*
*places.name
字段包含地点资源名称,格式为:places/PLACE_ID
。使用places.displayName
访问地点的文本名称。以下字段会触发“文本搜索(基本)SKU”:
places.accessibilityOptions
、places.addressComponents
、places.adrFormatAddress
、places.businessStatus
、places.displayName
、places.formattedAddress
、places.googleMapsUri
、places.iconBackgroundColor
、places.iconMaskBaseUri
、places.location
、places.photos
、places.plusCode
、places.primaryType
、places.primaryTypeDisplayName
、places.shortFormattedAddress
、places.subDestinations
、places.types
、places.utcOffsetMinutes
、{1places.viewport
以下字段会触发“文本搜索(高级)SKU”:
places.currentOpeningHours
、places.currentSecondaryOpeningHours
、places.internationalPhoneNumber
、places.nationalPhoneNumber
、places.priceLevel
、places.rating
、places.regularOpeningHours
、places.regularSecondaryOpeningHours
、places.userRatingCount
、places.websiteUri
以下字段会触发“文本搜索(首选)SKU”:
places.allowsDogs
、places.curbsidePickup
、places.delivery
、places.dineIn
、places.editorialSummary
、places.evChargeOptions
、places.fuelOptions
、places.goodForChildren
、places.goodForGroups
、places.goodForWatchingSports
、places.liveMusic
、places.menuForChildren
、places.parkingOptions
、places.paymentOptions
、places.outdoorSeating
、places.reservable
、places.restroom
、places.delivery
、places.delivery
、places.delivery
、places.delivery
{2places.reviews
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
textQuery
要搜索的文本字符串,例如:“餐馆”、“主街 123 号”或“旧金山最佳景点”。API 会根据此字符串返回候选匹配项,并按照其判断的相关性对结果进行排序。
可选参数
includedType
将结果限制为与表 A 定义的指定类型匹配的地点。只能指定一种类型。例如:
"includedType":"bar"
"includedType":"pharmacy"
languageCode
返回结果时使用的语言。
- 请参阅支持的语言列表。 Google 会经常更新支持的语言,因此该列表可能并非详尽无遗。
-
如果未提供
languageCode
,则 API 默认为en
。如果您指定的语言代码无效,API 将返回INVALID_ARGUMENT
错误。 - 该 API 会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标,它会返回当地语言的街道地址,如有必要,可将其音译为可由用户阅读的文字,同时遵循首选语言。所有其他地址均以首选语言返回。地址组成部分均以同一语言返回,该语言是从第一个组成部分中选择的语言。
- 如果某个名称在首选语言中没有对应项,则 API 会使用最接近的匹配项。
- 首选语言对 API 选择返回的结果集以及返回顺序的影响微乎其微。地理编码器会根据语言以不同的方式解读缩写,例如街道类型的缩写,或者使用一种语言有效但在另一种语言中无效的同义词。
locationBias
指定要搜索的区域。此位置充当偏差,这意味着可以返回指定位置周围的结果,包括指定区域以外的结果。
您可以指定
locationRestriction
或locationBias
,但不能同时指定这两者。您可以将locationRestriction
视为指定结果必须在哪个区域,将locationBias
视为指定结果必须靠近但可以位于该区域之外的区域。将区域指定为矩形视口或圆形。
圆形由中心点和半径(以米为单位)定义。半径必须介于 0.0 和 50000.0 之间(含 0.0 和 50000.0)。默认半径为 0.0。 例如:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.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
,则纬度范围为空。
必须填充“低”和“高”,并且表示的框不能为空。空视口会导致错误。
例如,以下视口可将纽约市完全包围:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- 如果
locationRestriction
指定要搜索的区域。系统不会返回指定区域以外的结果。将区域指定为矩形视口。如需了解如何定义视口,请参阅
locationBias
的说明。您可以指定
locationRestriction
或locationBias
,但不能同时指定这两者。您可以将locationRestriction
视为指定结果必须在哪个区域,将locationBias
视为指定结果必须靠近但可以位于该区域之外的区域。-
maxResultCount(已废弃)
指定每页显示的结果数(介于 1 到 20 之间)。 例如,如果将
maxResultCount
值设置为 5,则系统最多会在第一页上返回 5 个结果。如果查询可返回更多结果,则响应将包含nextPageToken
,您可以将该结果传递到后续请求中以访问下一页。 evOptions
指定用于识别可用电动汽车 (EV) 充电连接器和充电速率的参数。
connectorTypes
按地点可用的电动汽车充电连接器类型进行过滤。不支持任何连接器类型的地点将被滤除。 支持的电动汽车充电连接器类型包括组合式(交流和直流)充电器、特斯拉充电器、符合 GB/T 标准的充电器(适用于中国的电动汽车快速充电)和墙壁插座充电器。如需了解详情,请参阅参考文档。
minimumChargingRateKw
按最低电动汽车充电速率进行过滤,以千瓦 (kW) 为单位。如果地点的收费费率低于最低收费费率,则这些地点会被滤除。例如,如需查找充电速率至少为 10 kW 的电动汽车充电器,您可以将此参数设置为“10”。
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 的所有结果。
openNow
如果为
true
,则仅返回那些在发送查询时开门营业的地点。如果为false
,则返回所有商家,无论其处于营业状态如何。 如果将此参数设置为false
,则会返回未在 Google 地点数据库中指定营业时间的地点。pageSize
指定每页显示的结果数(介于 1 到 20 之间)。 例如,如果将
pageSize
值设置为 5,则系统最多会在第一页上返回 5 个结果。如果查询可返回更多结果,则响应将包含nextPageToken
,您可以将该结果传递到后续请求中以访问下一页。pageToken
指定上一页的响应正文中的
nextPageToken
。-
priceLevels
将搜索范围限制为特定价位的地点。 默认设置是选择所有价位。
指定一个数组,其中包含由
PriceLevel
定义的一个或多个值。例如:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
rankPreference
指定如何根据查询类型对结果在响应中的排名:
- 对于分类查询(例如“纽约市餐厅”),系统会默认使用
RELEVANCE
(按搜索相关性对结果进行排名)。您可以将rankPreference
设置为RELEVANCE
或DISTANCE
(按距离对结果排名)。 - 对于非分类查询(例如“Mountain View, CA”),我们建议您不要设置
rankPreference
。
- 对于分类查询(例如“纽约市餐厅”),系统会默认使用
regionCode
用于设置响应格式的地区代码,以 双字符 CLDR 代码值的形式指定。此参数也会对搜索结果产生偏差影响。没有默认值。
如果响应中
formattedAddress
字段的国家/地区名称与regionCode
匹配,则formattedAddress
中省略国家/地区代码。此参数不会影响adrFormatAddress
(如果可用时始终包含国家/地区名称)或shortFormattedAddress
(一律不包含国家/地区名称)。除了某些明显的例外情况之外,大多数 CLDR 代码都与 ISO 3166-1 代码相同。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(专指“大不列颠及北爱尔兰联合王国”)。 该参数可能会影响根据适用法律的结果。
strictTypeFiltering
与
includeType
参数搭配使用。设置为true
时,系统仅返回与includeType
指定的指定类型相匹配的地点。 默认情况下,如果为 false,响应可以包含与指定类型不匹配的地点。
文本搜索示例
通过查询字符串查找地点
以下示例显示了针对“Spicy Vegetarian Food in Sydney, Australia”的“文本搜索”请求:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
请注意,X-Goog-FieldMask
标头指定响应包含以下数据字段:places.displayName,places.formattedAddress
。然后,响应将采用以下格式:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, { "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Peace Harmony", "languageCode": "en" } }, ... ] }
向字段掩码添加更多数据类型,以返回其他信息。例如,添加 places.types,places.websiteUri
以在响应中包含餐厅类型和网址:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \ 'https://places.googleapis.com/v1/places:searchText'
现在,响应格式为:
{ "places": [ { "types": [ "vegetarian_restaurant", "vegan_restaurant", "chinese_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "websiteUri": "http://www.motherchusvegetarian.com.au/", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "types": [ "vegan_restaurant", "thai_restaurant", "vegetarian_restaurant", "indian_restaurant", "italian_restaurant", "american_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "websiteUri": "http://www.veggosizzle.com.au/", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
按价位过滤地点
使用 priceLevel
选项过滤结果,找出定义为“便宜”或“价格中等”的餐馆:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia", "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"] }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
此示例还使用 X-Goog-FieldMask
标头将 places.priceLevel
数据字段添加到响应,格式如下:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "115 King St, Newtown NSW 2042, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Green Mushroom", "languageCode": "en" } }, ... ] }
添加其他选项以缩小搜索范围,例如 includedType
、minRating
、rankPreference
、openNow
以及可选参数中所述的其他参数。
搜索某个区域内的地点
使用 locationRestriction
或 locationBias
(但不能同时使用这两者)将搜索范围限定在某个区域。您可以将 locationRestriction
视为指定结果必须在哪个区域,将 locationBias
视为指定结果必须靠近但可以位于该区域之外的区域。
以下示例展示了针对“辣味素食”的文本搜索请求,并将其自定义调整为位于旧金山市中心某个点的 500 米范围内。此请求仅返回营业地点的前 10 个结果。
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food", "openNow": true, "pageSize": 10, "locationBias": { "circle": { "center": {"latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } }, }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
搜索具有最低充电速率的电动汽车充电站
使用 minimumChargingRateKw
和 connectorTypes
搜索配有与您的电动汽车兼容的充电桩的地点。
以下示例展示了对位于加利福尼亚州山景城的特斯拉和 J1772 型 1 型电动汽车充电连接器的请求,最低充电功率为 10 kW。系统仅返回四个结果。
curl -X POST -d '{ "textQuery": "EV Charging Station Mountain View", "pageSize": 4, "evOptions": { "minimumChargingRateKw": 10, "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"] } }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \ 'https://places.googleapis.com/v1/places:searchText'
该请求会返回以下响应:
{ "places": [ { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 16, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 100, "count": 8, "availableCount": 5, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 2, "availableCount": 2, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 6, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 6, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 4, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 2, "availableCount": 0, "outOfServiceCount": 2, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 5, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_J1772", "maxChargeRateKw": 3.5999999046325684, "count": 1, "availableCount": 0, "outOfServiceCount": 1, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "Electric Vehicle Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 10, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_OTHER", "maxChargeRateKw": 210, "count": 10 } ] } } ] }
指定每页返回的结果数
使用 pageSize
参数指定每页返回的结果数。响应正文中的 nextPageToken
参数提供了一个令牌,该令牌可用于后续调用,以访问下一页结果。
以下示例展示了针对“北京烤鸭”的请求,每页限于 5 条结果:
curl -X POST -d '{ "textQuery": "pizza in New York", "pageSize": 5 }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.id,nextPageToken" \ 'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJifIePKtZwokRVZ-UdRGkZzs" }, { "id": "ChIJPxPd_P1YwokRfzLhSiACEoU" }, { "id": "ChIJrXXKn5NZwokR78g0ipCnY60" }, { "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE" }, { "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw" } ], "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }
如需访问下一页结果,请使用 pageToken
在请求正文中传入 nextPageToken
:
curl -X POST -d '{ "textQuery": "pizza in New York", "pageSize": 5, "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.id,nextPageToken" \ 'https://places.googleapis.com/v1/places:searchText'
{ "places": [ { "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw" }, { "id": "ChIJjaD94kFZwokR-20CXqlpy_4" }, { "id": "ChIJ6ffdpJNZwokRmcafdROM5q0" }, { "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM" }, { "id": "ChIJ8164qwFZwokRhplkmhvq1uE" } ], "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c" }
试试看!
借助 API Explorer,您可以发出示例请求,以便熟悉 API 和 API 选项。
选择页面右侧的 API 图标 。
(可选)展开显示标准参数,并将
fields
参数设置为字段掩码。(可选)修改请求正文。
选择执行按钮。在弹出的对话框中,选择要用于发出请求的帐号。
在 API Explorer 面板中,选择展开图标 ,以展开 API Explorer 窗口。