Destination 是指用户打算前往或导航到的重要兴趣点或特定位置。Destination 可以包含导航点、地标、入口和建筑物轮廓等信息。
通过 Geocoding API 的 SearchDestinations 端点，您可以根据不同的输入条件（例如地址、地点 ID 或纬度和经度坐标）检索有关各种目的地的详细信息。
搜索目的地请求
搜索目的地请求是指向以下格式的网址发出的 HTTP POST 请求：
https://geocode.googleapis.com/v4alpha/geocode/destinations
在 JSON 请求正文或标头中传递所有参数，作为 POST 请求的一部分。例如：
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
您可以通过以下 3 种方式之一指定要搜索目的地的位置：
- 地址
- 地点 ID
- 经纬坐标
按地址搜索目的地
您可以将地址指定为非结构化字符串：
curl -X POST -d '{
"addressQuery": {
"addressQuery": "601 S Bernardo Ave, Sunnyvale, CA 94087, USA"
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
或作为 postalAddress：
curl -X POST -d '{
"addressQuery": {
"address": {
"addressLines": ["601 S Bernardo Ave"],
"locality": "Sunnyvale",
"postalCode": "94087",
"administrativeArea": "CA",
"regionCode": "US"
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
在处理 HTML 表单中捕获的地址组成部分时，您通常会使用 postalAddress 格式。
按地点 ID 搜索目的地
您可以通过提供地点 ID 来检索目的地：
curl -X POST -d '{
"place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
按位置搜索目的地
您可以通过提供纬度和经度坐标来搜索目的地：
curl -X POST -d '{
"locationQuery": {
"location": {
"latitude": 37.37348780,
"longitude": -122.05678064
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
使用 OAuth 发出请求
Geocoding API v4 支持使用 OAuth 2.0 进行身份验证。如需将 OAuth 与 Geocoding API 搭配使用，必须为 OAuth 令牌分配正确的范围。Geocoding API 支持以下范围，可与 Destinations 端点搭配使用：
https://www.googleapis.com/auth/maps-platform.geocode- 与所有 Geocoding API 端点搭配使用。
此外，您还可以为所有 Geocoding API 端点使用常规 https://www.googleapis.com/auth/cloud-platform 范围。该范围在开发期间很有用，但在生产期间则不然，因为这是一个通用范围，允许访问所有端点。
如需了解详情和示例，请参阅使用 OAuth。
搜索目的地响应
SearchDestinations 会返回 SearchDestinationsResponse。
完整的 JSON 对象采用以下格式：
{ "destinations": [ { "primary": { "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w", "displayName": { "text": "Arby's", "languageCode": "en" }, "primaryType": "fast_food_restaurant", "types": [ "fast_food_restaurant", "sandwich_shop", "deli", "american_restaurant", "meal_takeaway", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Arby's, 601 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "601 S Bernardo Ave" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3734545, "longitude": -122.05693269999998 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.056930138027, 37.3735253692531 ], [ -122.056960139391, 37.3735372663597 ], [ -122.056994129366, 37.3734828786847 ], [ -122.056969677395, 37.3734731161089 ], [ -122.057061762447, 37.3733261309656 ], [ -122.056979388817, 37.3732935577128 ], [ -122.056798860285, 37.3735818838642 ], [ -122.056875858081, 37.3736121235316 ], [ -122.056930138027, 37.3735253692531 ] ] ] } }, "containingPlaces": [ { "place": "places/ChIJYfdAFum2j4ARIcL2tjME3Sw", "displayName": { "text": "Cherry Chase Shopping Center", "languageCode": "en" }, "primaryType": "shopping_mall", "types": [ "shopping_mall", "point_of_interest", "establishment" ], "formattedAddress": "Cherry Chase Shopping Center, 663 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1020", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "663 S Bernardo Ave" ] }, "structureType": "GROUNDS", "location": { "latitude": 37.3731231, "longitude": -122.0578211 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057112227103, 37.3714618008523 ], [ -122.057076849821, 37.3715743611411 ], [ -122.056963607756, 37.3719081793948 ], [ -122.056865279559, 37.3722026053835 ], [ -122.056687872374, 37.3727258358476 ], [ -122.056580005889, 37.3730511370747 ], [ -122.056498845827, 37.3732994782583 ], [ -122.056338259713, 37.3737878663325 ], [ -122.056618678291, 37.373887693582 ], [ -122.056912102521, 37.3740010327191 ], [ -122.057532418159, 37.3742476426462 ], [ -122.057673926626, 37.3742441740031 ], [ -122.057735663106, 37.3742328516943 ], [ -122.057766531332, 37.3742220604378 ], [ -122.057797572967, 37.37420520725 ], [ -122.057828267759, 37.3741852342085 ], [ -122.058060299297, 37.3740060842535 ], [ -122.058199726081, 37.3737861673422 ], [ -122.05836707267, 37.373524542556 ], [ -122.058569622393, 37.3732018598683 ], [ -122.0587638478, 37.3728890198039 ], [ -122.058934661823, 37.3726036257774 ], [ -122.059164956851, 37.3722498383629 ], [ -122.058997784906, 37.3721804442035 ], [ -122.057936479838, 37.3717605636234 ], [ -122.057495827092, 37.3715860151634 ], [ -122.057112227103, 37.3714618008523 ] ] ] } } ], "landmarks": [ { "place": { "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14", "displayName": { "text": "Safeway", "languageCode": "en" }, "primaryType": "grocery_store", "types": [ "grocery_store", "florist", "butcher_shop", "deli", "bakery", "food_delivery", "supermarket", "market", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Safeway, 639 S Bernardo Ave, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "639 S Bernardo Ave" ] }, "structureType": "POINT", "location": { "latitude": 37.3727912, "longitude": -122.0581172 } }, "tags": [ "ARRIVAL", "ADDRESS" ] }, { "place": { "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs", "displayName": { "text": "Starbird Chicken", "languageCode": "en" }, "types": [ "fast_food_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "Starbird Chicken, 1241 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1028", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1241 W El Camino Real" ] }, "structureType": "BUILDING", "location": { "latitude": 37.3746764, "longitude": -122.05708860000001 }, "displayPolygon": { "type": "Polygon", "coordinates": [ [ [ -122.057003840785, 37.3747648209809 ], [ -122.057136852459, 37.3747919153144 ], [ -122.057205005705, 37.3745815131859 ], [ -122.057071994114, 37.3745544186944 ], [ -122.057003840785, 37.3747648209809 ] ] ] } }, "tags": [ "ARRIVAL", "ADDRESS" ] }, { "place": { "place": "places/ChIJXXTe7Oi2j4ARoMTA-D6Hjpg", "displayName": { "text": "Chase Bank", "languageCode": "en" }, "primaryType": "bank", "types": [ "bank", "atm", "finance", "point_of_interest", "establishment" ], "formattedAddress": "Chase Bank, 1234 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1234 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.373579, "longitude": -122.05752700000001 } }, "tags": [ "ARRIVAL", "ADDRESS" ] }, { "place": { "place": "places/ChIJlbIO1Oi2j4ARp17Uf24xkHk", "displayName": { "text": "Madras Café", "languageCode": "en" }, "primaryType": "indian_restaurant", "types": [ "indian_restaurant", "coffee_shop", "cafe", "restaurant", "food_store", "food", "point_of_interest", "store", "establishment" ], "formattedAddress": "Madras Café, 1177 W El Camino Real, Sunnyvale, CA 94087, USA", "postalAddress": { "regionCode": "US", "languageCode": "en", "postalCode": "94087-1026", "administrativeArea": "CA", "locality": "Sunnyvale", "addressLines": [ "1177 W El Camino Real" ] }, "structureType": "POINT", "location": { "latitude": 37.3743, "longitude": -122.0549333 } }, "tags": [ "ARRIVAL", "ADDRESS" ] } ], "entrances": [ { "location": { "latitude": 37.373531299999996, "longitude": -122.05694519999999 }, "tags": [ "PREFERRED" ], "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w" } ], "navigationPoints": [ { "location": { "latitude": 37.3738659, "longitude": -122.05693620000001 }, "travelModes": [ "DRIVE", "WALK" ], "usages": [ "UNKNOWN" ] } ] } ] }
必需参数
- API 请求中必须包含以下 3 个参数之一，用于指定要搜索目的地的地址、地点或位置：
addressQuery- 要搜索的地址。place- 要搜索的地点 ID。locationQuery- 要搜索的位置的纬度和经度坐标。
FieldMask
通过创建响应字段掩码来指定要在响应中返回的字段列表。 使用网址参数
$fields或fields，或者使用 HTTP 标头X-Goog-FieldMask，将响应字段掩码传递给相应方法。例如，以下请求将仅返回主要目的地的入口、导航点和地点 ID。curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \ -H "X-Goog-Api-Key: API_KEY" \ -H "Content-Type: application/json" \ -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary.place" \ https://geocode.googleapis.com/v4alpha/geocode/destinations响应中没有默认的返回字段列表。如果您省略字段掩码，该方法会返回错误。将字段掩码设置为
*，以便返回所有字段。如需了解详情，请参阅选择要返回的字段。
可选参数
-
travelModes
指定要返回的
navigationPoints类型。 系统会滤除其他出行方式的导航点。如果未设置travelModes，则可以返回所有出行方式的导航点。 languageCode
返回结果所用的语言。
- 请参阅支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
-
如果未提供
languageCode，API 会默认使用en。如果您指定的语言代码无效，API 会返回INVALID_ARGUMENT错误。 - 该 API 会尽力提供用户和当地人都能看懂的街道地址。为了实现这一目标，它会返回本地语言的街道地址，并在必要时根据首选语言将地址音译为用户可读的文字。所有其他地址均以首选语言返回。地址组成部分全部以同一种语言返回，该语言是从第一个组成部分中选择的。
- 如果首选语言中没有相应名称，API 会使用最接近的匹配项。
- 首选语言对 API 选择返回的结果集以及返回顺序有一定影响。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或者在一种语言中有效但在另一种语言中无效的同义词。
regionCode
地区代码，以 双字符 CLDR 代码值表示。没有默认值。大多数 CLDR 代码都与 ISO 3166-1 代码完全一致。
在对地址进行地理编码（即正向地理编码）时，此参数可以影响但不会完全限制服务返回指定区域的结果。在对位置或地点进行地理编码时（反向地理编码或地点地理编码），可以使用此参数设置地址格式。在任何情况下，此参数都可能会根据适用法律影响结果。
反馈
这是 Geocoding API 的一个实验性端点。欢迎发送电子邮件至 geocoding-feedback-channel@google.com 提供反馈。