简介
获得地点 ID 后，您可以通过发起 “地点详情（新）” 请求来请求有关特定商家或 地图注点的更多详细信息。“地点详情（新）”请求会返回有关指定地点的更全面信息，例如完整地址、电话号码、房客评分和评价。
您可以通过多种方式获取地点 ID。您可以使用：
借助 APIs 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或者在 curl 命令中：
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
consumerAlert
id
movedPlace
movedPlaceId
name*
photos
*
name字段包含地点 资源名称，格式为：places/PLACE_ID。如需获取地点的文本名称，请在 Pro SKU 中请求displayName字段。如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。
以下字段会触发“地点详情要点”SKU：
addressComponents
addressDescriptor*
adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
* 地址描述符通常面向印度客户提供，在其他地区则处于实验阶段。
如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。
以下字段会触发“地点详情 Pro”SKU：
accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsTypeLabel
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
openingDate
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。
以下字段会触发“地点详情 Enterprise”SKU：
currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
transitStation
userRatingCount
websiteUri如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。
以下字段会触发“地点详情 Enterprise + 氛围”SKU：
allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries*
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
* 仅限文本搜索和附近搜索如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。
-
placeId
用于唯一标识地点的文本标识符，由 文本搜索（新）或 附近搜索（新）返回。 如需详细了解地点 ID，请参阅 地点 ID 概览。
字符串
places/PLACE_ID也称为地点 资源名称。在“地点详情（新）”“附近搜索（新）”和“文本搜索（新）”请求的响应中，此字符串包含在响应的name字段中。独立 地点 ID 包含在响应的id字段中。
可选参数
languageCode
用于返回结果的语言。
- 请参阅 支持的语言列表。Google 会经常更新 支持的语言，因此该列表可能并非详尽无遗。
-
如果未提供
languageCode，API 默认使用en。如果您指定了无效的语言代码，API 会返回INVALID_ARGUMENT错误。 - API 会尽力提供用户和当地人都能看懂的街道地址。为实现这一目标，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" } }
获取地址描述符
地址描述符提供有关地点位置的关系信息，包括附近的 标志性建筑和包含的区域。
以下示例展示了针对圣何塞一家购物中心内百货商店的“地点详情（新）”请求。在此示例中，您在字段掩码中添加了 addressDescriptors
：
curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: name,displayName,addressDescriptor"
响应包含请求中指定的地点、附近标志性建筑的列表及其 与地点的距离，以及区域列表及其与地点的包含关系：
{ "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "displayName": { "text": "Macy's", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "food", "movie_theater", "point_of_interest", "restaurant", "shoe_store", "shopping_mall", "store" ], "spatialRelationship": "WITHIN", "straightLineDistanceMeters": 220.29175 }, { "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4", "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4", "displayName": { "text": "Nordstrom", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 329.45178 }, { "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "displayName": { "text": "Monroe Parking Garage", "languageCode": "en" }, "types": [ "establishment", "parking", "point_of_interest" ], "straightLineDistanceMeters": 227.05153 }, { "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM", "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM", "displayName": { "text": "Studios Inn by Daiwa Living California Inc.", "languageCode": "en" }, "types": [ "establishment", "lodging", "point_of_interest", "real_estate_agency" ], "straightLineDistanceMeters": 299.9955 }, { "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "displayName": { "text": "Din Tai Fung", "languageCode": "en" }, "types": [ "establishment", "food", "point_of_interest", "restaurant" ], "straightLineDistanceMeters": 157.70943 } ], "areas": [ { "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "displayName": { "text": "Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM", "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM", "displayName": { "text": "Central San Jose", "languageCode": "en" }, "containment": "WITHIN" } ] } }
获取已搬迁地点的地点详情
如果您的应用中引用的地点已搬迁，您可以使用
movedPlace 和 movedPlaceId 字段获取新地点的详细信息。
对于已永久停业的地点，“地点详情（新）”会在
businessStatus字段中返回CLOSED_PERMANENTLY，并在响应正文中省略movedPlace和
movedPlaceId字段。
对于已搬迁到新地点 的地点，“地点详情（新）”会在CLOSED_PERMANENTLY 字段中返回
businessStatus，并在响应正文的movedPlace 和
movedPlaceId 字段中返回新地点。
对于未搬迁的地点，“地点详情（新）”不会在响应正文中返回
movedPlace或movedPlaceId。
以下示例请求有关加拿大魁北克省 Marche IGA St-Canut 的地点信息：
curl -X GET -H 'Content-Type: application/json' \ -H 'x-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \ https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ
请求会返回以下响应：
{ "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ", "businessStatus": "CLOSED_PERMANENTLY", "displayName": { "text": "Marche IGA St-Canut", "languageCode": "en" }, "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ", "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ" }
如需请求有关新地点的详细信息，请在新的“地点详情（新）”请求中使用 movedPlace 字段
中的地点资源名称。
对于多次搬迁 的地点，获取有关当前地点
的详细信息可能需要多个链接的“地点详情（新）”请求。地点结果的 movedPlace 和
movedPlaceId 字段仅指向下一个地点，而不是最近一次的已知地点。如果“地点详情（新）”请求
在响应正文中省略了 movedPlace 和 movedPlaceId 字段，则表示地点位于其 当前地点。
查找未来开业的商家
您可以请求有关预计未来开业的商家的详细信息。
如果预计开业日期至少包含月份且距离现在不到 90 天，附近搜索（新）将填充 openingDate 字段。
以下示例展示了针对爱达荷州新梅多斯未来开业商家的附近搜索（新）请求：
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,businessStatus,openingDate" \ "https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"
响应包含地点的商家状态和预计开业日期：
{ "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "openingDate": { "year": 2026, "month": 4, "day": 15 } }
获取公交车站信息
您可以使用“地点详情（新）”获取有关公交车站的信息。响应正文包含有关公交车站的信息，包括公交车站名称、关联的公交机构以及服务于该公交车站的公交线路。此外，响应还包含车辆图标和颜色，您可以使用这些图标和颜色来显示公交车站信息。
以下示例展示了针对中央车站的公交车站信息请求：
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,transitStation" \ "https://places.googleapis.com/v1/places/ChIJLVaKiQFZwokRgcybX3K6Pzg"
响应正文包含半径范围内的每个公交车站的信息、服务于该公交车站的线路、公交机构在该停靠点发布的提醒以及出发信息：
{ "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJ420yFwBZwokR903kVZLSsFc", "vehicleType": "SUBWAY", "displayName": { "text": "42 St Shuttle", "languageCode": "en" }, "shortDisplayName": { "text": "S", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#808183", "url": "https://www.mta.info/schedules/subway/42-st-shuttle", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, { "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM", "vehicleType": "SUBWAY", "displayName": { "text": "5 Train (Lexington Av Express)", "languageCode": "en" }, "shortDisplayName": { "text": "5 Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#00933C", "url": "https://www.mta.info/schedules/subway/5-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } } ... ] }, { "displayName": { "text": "MTA", "languageCode": "en" }, "url": "https://new.mta.info/", "lines": [ { "id": "ChIJcwVpzKpZwokR24EBeh8arww", "vehicleType": "BUS", "displayName": { "text": "United Nations - W 42 St Pier", "languageCode": "en" }, "shortDisplayName": { "text": "M42", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "Long Island Rail Road", "languageCode": "en" }, "url": "http://www.mta.info/lirr", "lines": [ { "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Ronkonkoma Branch", "languageCode": "en" }, "shortDisplayName": { "text": "LIRR", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#A626AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" } } ... ] } ], "stops": [ { "id": "ChIJRcemlf1YwokRhFqqw5jKBFM", "stopCode": { "text": "GCT" }, "location": { "latitude": 40.755161, "longitude": -73.975456 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJ57l2zANZwokRD1pyhuwpfKY", "signageText": { "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7", "languageCode": "en" }, "location": { "latitude": 40.750983, "longitude": -73.9750686 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc", "displayName": { "text": "E 42 St/Park Av", "languageCode": "en" }, "location": { "latitude": 40.7518199, "longitude": -73.9771918 }, "wheelchairAccessibleEntrance": true } ... ] } }
获取入口和导航点
您可以请求目的地的入口和导航点。入口定义了地点的出入口（例如，机场或购物中心的不同大门）。导航点定义了导航应结束的路边位置，这有助于将用户引导至道路的正确一侧或特定的下车点。
导航点会返回 navigationPointToken。您可以将此令牌传递给 Navigation SDK（适用于 Android 或 iOS）或 Routes API，以引导司机前往该特定位置。如需了解详情，请参阅导航点令牌。
以下示例请求旧金山国际机场（地点 ID ChIJVVVVVYx3j4ARP-3NGldc8qQ）的详细信息，并在字段掩码中包含 entrances 和 navigationPoints：
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,entrances,navigationPoints" \ https://places.googleapis.com/v1/places/ChIJVVVVVYx3j4ARP-3NGldc8qQ
响应包含地点的入口和导航点：
{ "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] }
试试看！
借助 APIs Explorer，您可以发出示例请求，以便熟悉 API 和 API 选项。
选择页面右侧的 API 图标 api 。
您可以选择修改请求参数。
选择执行 按钮。在对话框中，选择要用于发出请求的账号 。
在 APIs Explorer 面板中，选择全屏图标 fullscreen 以展开 APIs Explorer 窗口。