這項產品/功能為預先發布版 (正式發布前)。正式發布前的產品和功能僅提供有限支援，且對正式發布前的產品和功能所做的變更可能與其他正式發布前的版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範。詳情請參閱推出階段說明。

搜尋目的地

歐洲經濟區 (EEA) 開發人員

A Destination 是指使用者打算前往或導航至的重要景點或特定地點。Destination 可能包含導覽點、地標、入口和建築物輪廓等資訊。

您可以使用 Geocoding API 的 SearchDestinations 端點，根據不同的輸入條件 (例如地址、地點 ID 或經緯度座標)，擷取各種目的地的詳細資訊。

搜尋目的地要求

搜尋目的地要求是傳送至下列格式網址的 HTTP POST 要求：

https://geocode.googleapis.com/v4beta/geocode/destinations

在 POST 要求中，將所有參數傳遞至 JSON 要求內文或標頭。例如：

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/v4beta/geocode/destinations

您可以透過下列 3 種方式之一，指定要搜尋目的地的位置：

地址
地點 ID
經緯度座標

依地址搜尋目的地

您可以將地址指定為非結構化字串。地址地理編碼不會解析經緯度座標，或不代表地址的其他非結構化字串。系統不支援使用這類字串的要求，可能會導致錯誤回應或未指定的行為。不支援的查詢範例如下：

查詢類型	範例
經緯度座標。請改用位置查詢。	"37.422131,-122.084801"
概念或限制過多，例如單一查詢中包含多個地點、道路或城市名稱	「Market Street San Francisco San Jose Airport」
Google 地圖未顯示郵政地址元素	「C/O John Smith 123 Main Street」「P.O. Box 13 San Francisco」
商家、連鎖店或類別的名稱，加上這些實體不適用的地點	「德州達拉斯附近的 Tesco」
有多種解讀方式的模稜兩可查詢	「充電器退貨」
不再使用的舊名稱	"Middlesex United Kingdom"
非地理空間元素或意圖	「Ventura Harbor 有多少艘船？」
非官方或自訂名稱	「The Jenga」「The Helter Skelter」
大型政治實體 (城市、州/省、國家/地區)	"New York City" "California" "USA"
沒有特定地址的路線	「1st Ave., NYC, NY" "I-95"

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/v4beta/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/v4beta/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/v4beta/geocode/destinations

支援的地點 ID

Search Destinations 端點最適合搭配地點 ID 使用，代表可導覽的特定目的地。

一般來說，系統支援 establishment、point_of_interest、premise、street_address 和 subpremise 等類型的地點 ID。

不代表個別地點的地點 ID (例如從地址範圍推斷出的地點 ID，如「10-20 Main St」)、沒有特定號碼的路段，或 Plus Codes 不受支援。

使用 Place Autocomplete 尋找地點 ID 時，為確保相容性，請考慮依類型篩選結果。您可以在 Autocomplete 要求中使用 includedPrimaryTypes 參數，只納入上述支援的類型：

"includedPrimaryTypes": [ "establishment", "point_of_interest", "premise", "street_address", "subpremise" ]

這樣可確保 Place Autocomplete 傳回的地點 ID 最符合 Search Destinations 方法。請注意，establishment 型別很廣泛。雖然這個篩選器有助於擷取許多商家地點，但可能也會納入 natural_feature 類型的 Place Autocomplete 結果，而搜尋目的地僅支援這類結果的有限功能。

依地點搜尋目的地

你可以提供經緯度座標來搜尋目的地：

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/v4beta/geocode/destinations

使用 OAuth 提出要求

Geocoding API 第 4 版支援 OAuth 2.0 驗證。如要搭配 Geocoding API 使用 OAuth，OAuth 權杖必須指派正確的範圍。Geocoding API 支援下列範圍，可搭配 Destinations 端點使用：

https://www.googleapis.com/auth/maps-platform.geocode — 適用於所有 Geocoding API 端點。

此外，您也可以為所有 Geocoding API 端點使用一般 https://www.googleapis.com/auth/cloud-platform 範圍。這個範圍在開發期間很有用，但不適用於正式環境，因為這是允許存取所有端點的一般範圍。

如需更多資訊和範例，請參閱「使用 OAuth」。

搜尋目的地回應

地點的超地方化情境

搜尋目的地回應會提供豐富的超區域情境資訊。主要欄位包括：

primary：要求中查詢所識別的主要地點。
containingPlaces：主要目的地所屬的較大實體 (例如包含商店的購物中心)。
subDestinations：主要目的地內的更具體位置 (例如大樓內的公寓)。
entrances：目的地的特定進入和離開點。
navigationPoints：適合導覽至終點的道路附近位置。
arrivalSummary：AI 輔助洞察資料，協助你順利抵達目的地。請參閱「AI 輔助摘要」。
landmarks：附近的重要地點，可協助使用者瞭解目的地周圍環境。

如要進一步瞭解所有回應欄位，請參閱 API 參考資料。

回覆格式

SearchDestinations 會傳回下列 JSON 格式的 SearchDestinationsResponse：

{
  "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"
          ],
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 158.65607,
          "travelDistanceMeters": 131.16699
        },
        {
          "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"
          ],
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 87.34801,
          "travelDistanceMeters": 214.08084
        },
        {
          "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"
          ],
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 61.182194,
          "travelDistanceMeters": 63.075645
        },
        {
          "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"
          ],
          "relationalDescription": {
            "text": "Near Madras Café",
            "languageCode": "en"
          },
          "straightLineDistanceMeters": 204.45102,
          "travelDistanceMeters": 235.12041
        }
      ],
      "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/v4beta/geocode/destinations
  
```
回應中沒有預設的傳回欄位清單。如果省略欄位遮罩，這個方法會傳回錯誤。將欄位遮罩設為 *，即可傳回所有欄位。詳情請參閱「選擇要傳回的欄位」。

選用參數

travelModes

指定要傳回的 navigationPoints 類型。系統會篩除其他交通方式的導航點。如果未設定 travelModes，系統可能會傳回所有交通方式的導航點。
languageCode

傳回結果時使用的語言。
- 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
- 如未提供 languageCode，API 會預設為 en。如果指定無效的語言代碼，API 會傳回 INVALID_ARGUMENT 錯誤。
- API 會盡量提供使用者和當地人都能辨識的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要根據偏好語言，將地址音譯為使用者可讀取的文字。所有其他地址都會以偏好語言顯示。地址元件一律會以同一種語言傳回，而該語言是從第一個元件中選擇。
- 如果偏好語言沒有名稱，API 會使用最接近的名稱。
- 偏好語言對 API 選擇傳回的結果集和傳回順序影響不大。地理編碼器會根據語言解讀縮寫，例如街道類型縮寫，或在某種語言中有效但在另一種語言中無效的同義字。
regionCode

區域代碼，以雙字元 CLDR 代碼值表示。沒有預設值。大多數 CLDR 代碼與 ISO 3166-1 代碼相同。
對地址進行地理編碼 (正向地理編碼) 時，這個參數會影響服務傳回的結果，但不會完全限制結果只來自指定區域。進行地點或地點地理編碼時 (反向地理編碼或地點地理編碼)，這個參數可用來設定地址格式。在所有情況下，這個參數都可能根據適用法律影響結果。
placeFilter

可讓您篩選 locationQuery 搜尋結果，以符合您的需求，例如只傳回建築物目的地，或只傳回地址清楚的目的地。

依結構細微程度篩選

structureType 篩選器可讓您指定查詢傳回的結構類型：
- 隔離建築物：使用 "structureType": "BUILDING" 在地圖上顯示建築物輪廓，或取得特定建築物的詳細資料。
- 瞭解複合物：使用 "structureType": "GROUNDS" 確保主要結果是整體地面。查詢大學校園或購物中心等較大區域時，這項功能就非常實用。
- 著重於單位/區段：使用 "structureType": "SECTION" 識別建築物內的區段。
確保地址實用性

並非所有地點都有清楚的街道地址。addressability篩選器可協助控管結果中的地址品質：
- 要求提供明確的主要地址：為確保主要目的地結果一律包含街道層級的地址或名稱，請使用 "addressability": "PRIMARY"。如果導覽或顯示用途需要清楚的地址，這項功能就十分實用。
- 允許子目的地中的地址：如果主要地點可能沒有地址，但其中的單元有地址 (例如大樓中的公寓)，"addressability": "WEAK" 可確保至少主要地點或其中一個子目的地有地址。
- 任何結果：如果地址存在與否與您的用途無關，請使用 "addressability": "ANY"。
範例：篩選可定址的建築物
```
curl -X POST -d '{
  "locationQuery": {
    "location": {
      "latitude": 37.37348780,
      "longitude": -122.05678064
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "PRIMARY"
    }
  },
  "languageCode": "en"
}' \\
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \\
-H "X-Goog-FieldMask: place" \\
https://geocode.googleapis.com/v4beta/geocode/destinations
```

意見回饋

這是 Geocoding API 的實驗性端點。歡迎傳送電子郵件至 geocoding-feedback-channel@google.com 提供意見。

搜尋目的地 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

搜尋目的地要求

依地址搜尋目的地

依地點 ID 搜尋目的地

支援的地點 ID

依地點搜尋目的地

使用 OAuth 提出要求

搜尋目的地回應

地點的超地方化情境

回覆格式

必要參數

FieldMask

選用參數

travelModes

languageCode

regionCode

placeFilter

依結構細微程度篩選

確保地址實用性

意見回饋

搜尋目的地