附近搜索(新) 请求采用一个或多个地点类型,并返回 资源。指定一种或多种数据类型的字段掩码 为必填字段。附近搜索(新)仅支持 POST 请求。
利用 API Explorer,您可以发出实时请求,从而熟悉 API 和 API 选项:
试试看!尝试互动式 演示,查看地图上显示的“附近搜索(新)”结果。
“附近搜索(新)”请求
“附近搜索(新)”请求是对 表单:
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
“附近搜索(新)”回复
附近搜索(新)会返回 <ph type="x-smartling-placeholder"></ph> JSON 对象作为响应。在响应中:
完整的 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
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
*places.name
字段包含地点资源名称 格式为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.reviews
,places.servesBeer
,places.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
过滤与 位置。当您指定常规主要类型(例如
"restaurant"
或"hotel"
,则响应可以包含具有更具体的主要类型(而非 指定的对象。例如,您指定的主要类型是"restaurant"
。然后,响应可以包含主要类型为"restaurant"
,但响应也可能会包含地点 主要类型,例如"chinese_restaurant"
或"seafood_restaurant"
。如果指定了多个类型限制的搜索,则只有地点 返回满足所有限制条件的应用例如,如果您指定
{"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(默认值),包括 1 和 20。
-
rankPreference
要使用的排名类型。如果省略此参数,则结果将按热门程度排名。 可以是以下其中一项:
POPULARITY
(默认):根据热门程度对结果进行排序。DISTANCE
,根据结果与 指定位置。
-
regionCode
用于设置响应格式的地区代码,指定为 <ph type="x-smartling-placeholder"></ph> 两个字符的 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" } }, ... }
查找多种类型的地点
以下示例展示了针对
周围 1000 米半径范围内所有便利店和酒类商店的显示名称
指定的 circle
:
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 图标
, 。
- (可选)展开显示标准参数,并设置
fields
参数 字段掩码。 - (可选)修改请求正文。
- 选择执行按钮。在弹出式窗口中,选择您要用于发出请求的账号。
在 API Explorer 面板中,选择“展开”图标,
用于展开 API Explorer 窗口。