附近搜索(新)请求可接受一个或多个地点类型,并返回指定区域内匹配的地点列表。必须指定一个或多个数据类型的字段掩码。附近搜索(新)仅支持 POST 请求。
借助 API Explorer,您可以发出实时请求,以便您熟悉 API 和 API 选项:
试试看!试用互动式演示,查看地图上显示的“附近搜索(新)”结果。
“附近搜索(新)”请求
“附近搜索(新)”请求是对网址的 HTTP POST 请求,格式如下:
https://places.googleapis.com/v1/places:searchNearby
将 JSON 请求正文或标头中的所有参数作为 POST 请求的一部分传递。例如:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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" \ https://places.googleapis.com/v1/places:searchNearby
“附近搜索(新)”回复
“附近搜索(新)”会返回 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: *
指定以下一个或多个字段:
以下字段会触发附近搜索(基本)SKU:
places.accessibilityOptions
、places.addressComponents
、places.adrFormatAddress
、places.attributions
、places.businessStatus
、places.displayName
、places.formattedAddress
、places.googleMapsUri
、places.iconBackgroundColor
、places.iconMaskBaseUri
、places.id
、places.location
、places.name
*、places.photos
、places.plusCode
、places.primaryType
、places.primaryTypeDisplayName
、 {/}2 、places.shortFormattedAddress
、 {2places.name
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
使用places.displayName
访问地点的文本名称。以下字段会触发附近搜索(高级)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.reviews
、places.servesBeer
、places.servesBeer
、{19places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
要搜索的区域,以圆形表示,由中心点和半径(以米为单位)定义。半径必须介于 0.0 和 50000.0 之间(含 0.0 和 50000.0)。默认半径为 0.0。您必须在请求中将其设置为大于 0.0 的值。
例如:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
可选参数
-
includeTypes/excludedTypes,containsPrimaryTypes/excludedPrimaryTypes
允许您指定表 A 中用于过滤搜索结果的类型中的一系列类型。每个类型限制类别中最多可以指定 50 种类型。
一个地点只能有一个关联的表 A 类型中的一个主要类型。例如,主要类型可能是
"mexican_restaurant"
或"steak_house"
。使用includedPrimaryTypes
和excludedPrimaryTypes
可按地点的主要类型过滤结果。地点还可以关联表 A 的类型中的多个类型值。例如,餐馆可能具有以下类型:
"seafood_restaurant"
、"restaurant"
、"food"
、"point_of_interest"
、"establishment"
。使用includedTypes
和excludedTypes
可在与某个地点关联的类型列表中过滤结果。如果指定了多项类型限制的搜索,则系统只会返回满足所有限制的地点。例如,如果您指定
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
,则返回的地点会提供"restaurant"
相关服务,但不会主要作为"steak_house"
运行。includedTypes
表 A 中要搜索的地点类型的逗号分隔列表。如果省略此参数,系统会返回所有类型的地点。
excludedTypes
表 A 中要排除在搜索范围外的地点类型的逗号分隔列表。
如果您在请求中同时指定
includedTypes
(例如"school"
)和excludedTypes
(例如"primary_school"
),则响应会包含归类为"school"
但不归类为"primary_school"
的地点。响应中包含与以下至少一个includedTypes
匹配且与任何excludedTypes
都不匹配的地点。如果存在任何冲突的类型(例如,某个类型同时出现在
includedTypes
和excludedTypes
中),则会返回INVALID_REQUEST
错误。includedPrimaryTypes
表 A 中要包含在搜索中的主要地点类型的英文逗号分隔列表。
excludedPrimaryTypes
表 A 中要排除在搜索范围外的主要地点类型的英文逗号分隔列表。
如果有任何主要类型存在冲突(例如,某个类型同时出现在
includedPrimaryTypes
和excludedPrimaryTypes
中),则会返回INVALID_ARGUMENT
错误。 -
languageCode
返回结果时所使用的语言。
- 请参阅支持的语言列表。Google 会经常更新支持的语言,因此该列表可能并不详尽。
- 如果未提供
languageCode
,则 API 默认为en
。如果您指定的语言代码无效,API 会返回INVALID_ARGUMENT
错误。 - API 会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标,它会以当地语言返回街道地址,必要时将其音译为用户可以看懂的脚本,并观察首选语言。所有其他地址均以首选语言返回。所有地址组成部分均以从第一个组成部分中选择的语言返回。
- 如果名称在首选语言中没有对应项,API 会使用最接近的匹配项。
- 首选语言对 API 选择返回的结果集以及结果的返回顺序有较小的影响。地理编码器会根据语言对缩写的解读方式不同,例如街道类型的缩写,或可能在一种语言中有效但不在另一种语言中的同义词。
-
maxResultCount
指定要返回的地点结果的数量上限。必须介于 1 到 20(默认值)之间(包括这两个数值)。
-
rankPreference
要使用的排名类型。如果省略此参数,则结果将按热门程度排名。 可以是以下其中一项:
POPULARITY
(默认):根据热门程度对结果进行排序。DISTANCE
根据结果与指定位置的距离按升序对结果进行排序。
-
regionCode
用于设置响应格式的地区代码,以 双字符 CLDR 代码值的形式指定。没有默认值。
如果响应中
formattedAddress
字段的国家/地区名称与regionCode
匹配,则formattedAddress
中省略国家/地区代码。此参数不会影响adrFormatAddress
(始终包含国家/地区名称)或shortFormattedAddress
(始终包含国家/地区名称)。大多数 CLDR 代码与 ISO 3166-1 代码相同,但也有一些值得注意的例外情况。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(特指“大不列颠及北爱尔兰联合王国”)。 根据适用法律,该参数可能会影响结果。
附近搜索(新)示例
查找一种类型的地点
以下示例展示了针对 500 米半径范围内所有餐厅的显示名称(由 circle
定义)的“附近搜索(新)”请求:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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" \ https://places.googleapis.com/v1/places:searchNearby
请注意,X-Goog-FieldMask
标头指定响应包含以下数据字段:places.displayName
。然后,响应将采用以下格式:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
向字段掩码添加更多数据类型以返回其他信息。例如,添加 places.formattedAddress,places.types,places.websiteUri
以在响应中包含餐馆地址、类型和网址:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
响应现在采用以下格式:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
查找多种类型的地点
以下示例展示了针对指定 circle
半径 1000 米内所有便利店和酒类商店的显示名称的“附近搜索(新)”请求:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearby此示例将
places.primaryType
和 places.types
添加到字段掩码中,以便在响应中包含每个地点的相关类型信息,从而更轻松地从结果中选择适当的地点。
从搜索中排除某个地点类型
以下示例展示了针对 "school"
类型的所有地点(不包括 "primary_school"
类型的所有地点)的“附近搜索(新)”请求,并按距离对结果进行排序:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
搜索某个区域附近的所有地点(按距离排名)
以下示例展示了针对旧金山市中心某个点附近地点的“附近搜索(新)”请求。在以下示例中,您可以添加 rankPreference
参数以按距离对结果进行排序:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
试试看!
在 API Explorer 中,您可以发出示例请求,以便您熟悉 API 和 API 选项。
- 选择页面右侧的 API 图标 。
- (可选)展开显示标准参数 (Show standard parameters),并将
fields
参数设置为字段掩码。 - (可选)修改请求正文。
- 选择执行按钮。在弹出式窗口中,选择您要用于发出请求的账号。
在 API Explorer 面板中,选择展开图标 以展开 API Explorer 窗口。