有了地点 ID 后,您可以发起地点详情(新)请求,以获取有关特定场所或地图注点的更多详细信息。“地点详情(新)”请求会返回有关指定地点的更全面信息,例如完整地址、电话号码、用户评分和评价。
获取地点 ID 的方法有很多。您可以使用:
借助 API Explorer,您可以发出实时请求,以便熟悉 API 和 API 选项:
“地点详情(新)”请求
地点详情请求是一种 HTTP GET 请求,格式如下:
https://places.googleapis.com/v1/places/PLACE_ID
将所有参数作为网址参数传递,或在 GET 请求的标头中传递。例如:
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY
或者在 c网址 命令中:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key:API_KEY " \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
“地点详情(新)”响应
“地点详情(新)”会 返回 JSON 对象作为响应。在回复中:
完整的 JSON 对象的形式如下:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
必需参数
-
FieldMask
通过创建响应字段掩码,指定要在响应中返回的字段列表。 使用网址参数
$fields
或fields
,或使用 HTTP 标头X-Goog-FieldMask
将响应字段掩码传递给该方法。响应中没有返回字段的默认列表。 如果您省略字段掩码,该方法会返回错误。字段遮盖是一种良好的设计做法,可确保您不会请求不必要的数据,这有助于避免产生不必要的处理时间和结算费用。
以逗号分隔列表的形式指定要返回的地点数据类型。例如,检索地点的显示名称和地址。
X-Goog-FieldMask: displayName,formattedAddress
使用
*
可以检索所有字段。X-Goog-FieldMask: *
指定以下一个或多个字段:
以下字段会触发地点详情(仅 ID)SKU:
attributions
、id
、name
*、photos
*name
字段包含地点资源名称,格式为:places/PLACE_ID
。使用displayName
访问地点的文本名称。以下字段会触发地点详情(仅位置)SKU:
addressComponents
、adrFormatAddress
、formattedAddress
、location
、plusCode
、shortFormattedAddress
、types
、viewport
以下字段会触发地点详情(基本)SKU:
accessibilityOptions
、businessStatus
、containingPlaces
、displayName
、googleMapsLinks
*、googleMapsUri
、iconBackgroundColor
、iconMaskBaseUri
、primaryType
、primaryTypeDisplayName
、pureServiceAreaBusiness
、subDestinations
、utcOffsetMinutes
*googleMapsLinks
字段处于正式发布前预览阶段,在预览期间使用不会产生费用,也就是说,结算金额为 0 美元。以下字段会触发地点详情(高级)SKU:
currentOpeningHours
、currentSecondaryOpeningHours
、internationalPhoneNumber
、nationalPhoneNumber
、priceLevel
、priceRange
、rating
、regularOpeningHours
、regularSecondaryOpeningHours
、userRatingCount
、websiteUri
以下字段会触发地点详情(首选)SKU:
allowsDogs
、curbsidePickup
、delivery
、dineIn
、editorialSummary
、evChargeOptions
、fuelOptions
、goodForChildren
、goodForGroups
、goodForWatchingSports
、liveMusic
、menuForChildren
、parkingOptions
、paymentOptions
、outdoorSeating
、reservable
、restroom
、reviews
、routingSummaries
、*servesBeer
、servesBreakfast
、servesBrunch
、servesCocktails
、servesCoffee
、servesDessert
、servesDinner
、servesLunch
、servesVegetarianFood
、servesWine
、takeout
*仅限文本搜索和附近搜索
-
placeId
一个文本标识符,用于唯一标识地点,从文本搜索(新版)或附近搜索(新版)返回。 如需详细了解地点 ID,请参阅地点 ID 概览。
字符串
places/PLACE_ID
也称为地点资源名称。在“地点详情(新)”“附近搜索(新)”和“文本搜索(新)”请求的响应中,此字符串包含在响应的name
字段中。独立地点 ID 包含在响应的id
字段中。
可选参数
languageCode
返回结果时所用的语言。
- 请参阅支持的语言列表。Google 会经常更新支持的语言,因此该列表可能并非详尽无遗。
-
如果未提供
languageCode
,则 API 默认为en
。如果您指定的语言代码无效,则 API 会返回INVALID_ARGUMENT
错误。 - 该 API 会尽力提供对用户和当地人而言都易于读取的街道地址。为实现此目标,它会以当地语言返回街道地址,并根据首选语言,视需要转写为用户可读的脚本。系统会以首选语言返回所有其他地址。地址组成部分均以相同的语言返回,该语言从第一个组成部分中选择。
- 如果名称不以首选语言提供,API 会使用最接近的匹配项。
- 首选语言对 API 选择返回的结果集和返回结果的顺序有一定影响。地理编码器会根据语言不同来解读缩写,例如街道类型的缩写,或者在一种语言中有效但在另一种语言中无效的同义词。
regionCode
用于设置响应格式的地区代码,指定为 两个字符的 CLDR 代码值。没有默认值。
如果响应中
formattedAddress
字段的国家/地区名称与regionCode
匹配,则formattedAddress
中会省略国家/地区代码。 此参数对adrFormatAddress
(始终包含国家/地区名称)或shortFormattedAddress
(从不包含国家/地区名称)没有影响。除了某些明显的例外情况之外,大多数 CLDR 代码都与 ISO 3166-1 代码完全一致。例如,英国的 ccTLD 为“uk”(.co.uk),但其 ISO 3166-1 代码为“gb”(从技术层面来说,适用于“大不列颠及北爱尔兰联合王国”实体)。 此参数可能会根据适用法律影响结果。
-
sessionToken
会话令牌是用户生成的字符串,用于将“自动补全(新)”调用作为“会话”进行跟踪。“自动补全”(新)使用会话令牌将用户自动补全搜索的查询和地点选择阶段归入不同的会话,以便进行结算。会话令牌会传递到自动补全(新)调用后面的地点详情(新)调用中。如需了解详情,请参阅会话令牌。
地点详情示例
以下示例通过 placeId
请求地点的详细信息:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key:API_KEY " \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
请注意,X-Goog-FieldMask
标头指定了响应包含以下数据字段:id,displayName
。然后,响应格式如下:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
向字段掩码添加更多数据类型,以返回其他信息。例如,添加 formattedAddress,plusCode
以在响应中添加地址和Plus Code:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key:API_KEY " \ -H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
响应现在的格式如下:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "plusCode": { "globalCode": "849VCWC7+RW", "compoundCode": "CWC7+RW Mountain View, CA, USA" }, "displayName": { "text": "Googleplex", "languageCode": "en" } }
试试看!
借助 API Explorer,您可以发出示例请求,以便熟悉 API 和 API 选项。
选择页面右侧的 API 图标 api。
(可选)修改请求参数。
选择执行按钮。在对话框中,选择您要用于发出请求的账号。
在 APIs Explorer 面板中,选择全屏图标 fullscreen 以展开 APIs Explorer 窗口。