Geocoding API 第 4 版方法的預設配額為每秒 25 次查詢 (QPS)。如要瞭解如何申請提高配額，請參閱「查看及管理配額」，然後選取「Geocoding API」做為服務。

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

搜尋目的地

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

Destination 是指使用者想前往或導航至的特定位置或地點。Destination 也包含與位置或地點相關的資訊集合，例如導航點、地標、入口和建築物輪廓。

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

搜尋目的地要求

搜尋目的地要求是 HTTP POST 要求，網址格式如下：

https://geocode.googleapis.com/v4/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/v4/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"
非地理空間元素或意圖	「文圖拉港有多少艘船？」
非官方或自訂名稱	「疊疊樂」「螺旋滑梯」
大型政治實體 (城市、州/省、國家/地區)	"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/v4/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/v4/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/v4/geocode/destinations

支援的地點 ID

搜尋目的地方法最適合用於代表特定可導航目的地的地點 ID。一般支援 establishment、point_of_interest、premise、street_address 和 subpremise 等類型的地點 ID。不支援不代表特定位置的地點 ID，例如從地址範圍推斷出的地點 ID (例如「10-20 Main St」)、沒有特定編號的路段，或 Plus Code。如果結果的地點 ID 涵蓋範圍過大 (例如「太平洋」)，系統也不支援。

搭配使用 Autocomplete (新版) 和 Search Destinations

為確保相容性，請使用 Autocomplete (新版) 尋找要與 Search Destinations 搭配使用的地點 ID。使用 Autocomplete (新版) 時，請務必使用 includedPrimaryTypes 參數，依類型篩選結果。Autocomplete (新版) 使用下列建議篩選條件傳回的地點 ID，可由 Search Destinations 支援：

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

此外，請勿在 Autocomplete (新版) 要求中，將 include_pure_service_area_businesses 標記設為 true。

依地點搜尋目的地

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

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/v4/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 方法。

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

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

搜尋目的地回應

Search Destinations 回應會提供該地點的豐富超地方資訊。

Search Destinations 回應中的 PlaceView 物件 (例如 primary、containingPlaces 中的項目和 landmarks) 會使用欄位指出地點類型：

types：字串陣列，表示地點類型。
primaryType：表示地點主要類型的字串。

types 和 primaryType 的可能字串值，取自「地點類型 (新版)」頁面的表 A 和表 B。

本節說明重要的回應欄位。如要進一步瞭解所有回應欄位，請參閱 API 參考資料。

`primary`

要求中查詢識別的主要地點。

`addressComponents`

這個陣列包含這個地址適用的各種元件。

每個地址元件通常會包含下列欄位：

types[] 是一個陣列，用來指出地址元件的類型。請參閱支援類型清單。
longText 是地理編碼器所傳回地址元件的完整文字說明或名稱。
shortText 是地址元件的縮寫文字名稱 (如有)。舉例來說，阿拉斯加州地址元件的 longText 可能為「Alaska」，而 shortText 則為兩個字母的郵政簡碼「AK」。
languageCode 是用來設定這個元件格式的語言，以 CLDR 標記法表示。

`containingPlaces`

主要目的地所屬的大型實體 (例如包含商店的購物中心)。

`subDestinations`

主要目的地內更具體的位置 (例如大樓內的公寓)。

`entrances`

entrances[] 陣列中的物件包含下列欄位：

displayName

LocalizedText 物件，包含入口的人類可讀名稱 (例如 "South Bernardo Avenue" 或 "5th Avenue")，如果有的話。
location

一組經緯度座標，定義地點的出入口位置。
entrance_tags[]

描述入口特徵的入口標記陣列。支援的值如下：
- "PREFERRED"
表示這個入口可能提供前往傳回地點的實際通道。一個地點可以有多個偏好入口。如果入口沒有這個標記，表示入口位於同一棟建築物，但不一定能通往該地點。

舉例來說，如果傳回的地點是購物中心內的餐廳，"PREFERRED" 入口會是通往餐廳本身的入口，其他傳回的入口則是建築物的其他入口，例如購物中心內其他餐廳的入口。

如果傳回的地點是建築物本身，"PREFERRED" 入口會是通往建築物「主要」部分的入口。舉例來說，在購物中心，"PREFERRED" 入口是通往主要門廳區域的入口，但如果入口只能通往建築物側邊的商店，則不屬於 "PREFERRED" 入口。
streetViewThumbnail和streetViewAnnotation

街景服務 Static API 的參數，可讓您顯示這些地點的相關圖像。進一步瞭解這些欄位。

`structureType`

這個地點代表的建築物類型。

POINT

點位置。
SECTION

建築物的子區段。
BUILDING

建築物。
GROUNDS

通常包含多棟建築物的大型區域，例如大學校園、公寓大樓或購物中心。

`navigationPoints`

Geocoding 回應中的 navigationPoints 欄位包含一系列點，可用於導航至該地點。具體來說，在道路網路中規劃往返該地點的路線時，應將這些點做為起點或終點。

每個導航點都包含下列值：

navigationPointToken 是包含 navigationPoints 欄位中比對內容資訊的權杖。您可以將這個權杖傳送至路線規劃和導航 API，改善應用程式中的路線規劃和河流體驗。詳情請參閱「使用導航點權杖規劃路線」。
location 包含導航點的經緯度值。這個位置一律會非常靠近道路網路，是導航至某個地點或從某個地點出發的理想停靠點或起點。這個點會刻意稍微偏離道路中心線，清楚標示地點位於道路的哪一側。
travelModes 是可從導航點存取的交通方式清單：
- "DRIVE" 是對應行車路線的交通方式。
- "WALK" 是步行路線對應的交通方式。
usages 是導航點支援的用途清單。用途包括：
- "DROPOFF"
- "PICKUP"
- "PARKING"

如為接送地點，請使用交通方式為 DRIVE 且用途為 PICKUP 或 DROPOFF 的導航點。如果沒有上車或下車地點，請使用最上方的行車導航點。

streetViewThumbnail 和 entranceAnnotation 為 Street View Static API 提供參數，讓您顯示這些地點的相關圖像。進一步瞭解這些欄位。

altitude_meters 包含導航點的海拔高度，以公尺為單位，相對於 WGS-84 橢球體。如果路段垂直堆疊，請使用 altitude_meters 欄位，讓系統選擇最適合導航的路段。

`landmarks`

附近地點，協助使用者瞭解目的地周遭環境。

每個地標都包含下列欄位：

place 是代表這個地標的 PlaceView 物件。
relationalDescription 是人類可讀的說明，指出目的地與地標的關係，例如「在帝國大廈附近」或「在白宮對面」。
tags[] 是一組標記，說明地標在目的地情境中的用途：
- "ADDRESS"：當地知名地點，可用來識別目的地的大概位置。
- "ARRIVAL"：可用來協助抵達目的地的地點，在接近目的地時有助於導航。
straightLineDistanceMeters 是從這個地標到目的地的直線距離 (以公尺為單位)。
travelDistanceMeters 是從這個地標到目的地的步行距離 (以公尺為單位)。

`arrivalSummary`

AI 輔助洞察資料，協助你抵達目的地。請參閱「AI 輔助摘要」。

`parkingOptions`

詳細停車資訊。

回覆格式

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",
          "meal_takeaway",
          "food_delivery",
          "american_restaurant",
          "restaurant",
          "food_store",
          "store",
          "food",
          "point_of_interest",
          "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/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
            }
          },
          "relationalDescription": {
            "text": "Near Chase Bank",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 61.182193756103516,
          "travelDistanceMeters": 63.075645446777344
        },
        {
          "place": {
            "place": "places/ChIJteQ0Fum2j4ARGi3tqK4Zm14",
            "displayName": {
              "text": "Safeway",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "butcher_shop",
              "florist",
              "deli",
              "supermarket",
              "bakery",
              "food_delivery",
              "market",
              "manufacturer",
              "food_store",
              "store",
              "food",
              "service",
              "point_of_interest",
              "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
            }
          },
          "relationalDescription": {
            "text": "Around the corner from Safeway",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL",
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 158.65606689453125,
          "travelDistanceMeters": 131.1669921875
        },
        {
          "place": {
            "place": "places/ChIJu-PSYui2j4ARNiwOwBApGqk",
            "displayName": {
              "text": "Oil Changers",
              "languageCode": "en"
            },
            "types": [
              "car_repair",
              "service",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Oil Changers, 1240 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1240 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3743054,
              "longitude": -122.0584272
            }
          },
          "relationalDescription": {
            "text": "Down the road from Oil Changers",
            "languageCode": "en"
          },
          "tags": [
            "ARRIVAL"
          ],
          "straightLineDistanceMeters": 140.52459716796875,
          "travelDistanceMeters": 143.24220275878906
        },
        {
          "place": {
            "place": "places/ChIJKRbl5oG3j4ARwuvPGUmtCj0",
            "displayName": {
              "text": "Apni Mandi Farmers Market Sunnyvale",
              "languageCode": "en"
            },
            "primaryType": "grocery_store",
            "types": [
              "grocery_store",
              "cake_shop",
              "supermarket",
              "asian_grocery_store",
              "indian_restaurant",
              "meal_takeaway",
              "bakery",
              "manufacturer",
              "wholesaler",
              "restaurant",
              "food_store",
              "store",
              "food",
              "point_of_interest",
              "establishment"
            ],
            "formattedAddress": "Apni Mandi Farmers Market Sunnyvale, 1111 W El Camino Real, Sunnyvale, CA 94087, USA",
            "postalAddress": {
              "regionCode": "US",
              "languageCode": "en",
              "postalCode": "94087-1056",
              "administrativeArea": "CA",
              "locality": "Sunnyvale",
              "addressLines": [
                "1111 W El Camino Real"
              ]
            },
            "structureType": "POINT",
            "location": {
              "latitude": 37.3737199,
              "longitude": -122.0522958
            }
          },
          "relationalDescription": {
            "text": "Near Apni Mandi Farmers Market Sunnyvale",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 410.37435913085938,
          "travelDistanceMeters": 479.49893188476562
        },
        {
          "place": {
            "place": "places/ChIJ8enMlui2j4AR2xXK5EHDhBs",
            "displayName": {
              "text": "Starbird Chicken",
              "languageCode": "en"
            },
            "primaryType": "chicken_restaurant",
            "types": [
              "chicken_restaurant",
              "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": {
              "coordinates": [
                [
                  [
                    -122.057003840785,
                    37.3747648209809
                  ],
                  [
                    -122.057136852459,
                    37.3747919153144
                  ],
                  [
                    -122.057205005705,
                    37.3745815131859
                  ],
                  [
                    -122.057071994114,
                    37.3745544186944
                  ],
                  [
                    -122.057003840785,
                    37.3747648209809
                  ]
                ]
              ],
              "type": "Polygon"
            }
          },
          "relationalDescription": {
            "text": "Near Starbird Chicken",
            "languageCode": "en"
          },
          "tags": [
            "ADDRESS"
          ],
          "straightLineDistanceMeters": 87.348007202148438,
          "travelDistanceMeters": 214.08084106445312
        }
      ],
      "entrances": [
        {
          "displayName": {
            "text": "South Bernardo Avenue",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.3735328,
            "longitude": -122.05694879999999
          },
          "tags": [
            "PREFERRED"
          ],
          "place": "places/ChIJY8sv5-i2j4AR_S6BlDDR42w"
        }
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJeMt61tqvQkARWT2716SDXsASEgljyy_n6LaPgBH9LoGUMNHjbBoSCWPLL-foto-AEf0ugZQw0eNsIhIJhf5y6ei2j4ARz7yBW5KAPI4",
          "location": {
            "latitude": 37.3738659,
            "longitude": -122.05693620000001
          },
          "travelModes": [
            "DRIVE",
            "WALK"
          ],
          "usages": [
            "PARKING"
          ]
        }
      ]
    }
  ]
}

必要參數

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/v4/geocode/destinations
  
```
回應中沒有預設的傳回欄位清單。如果省略欄位遮罩，方法會傳回錯誤。將欄位遮罩設為 *，即可傳回所有欄位。詳情請參閱「選擇要傳回的欄位」。

選用參數

travelModes

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

傳回結果時使用的語言。
- 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
- 如未提供 languageCode，API 預設會使用該地點的當地語言和文字。如果指定的語言代碼無效，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/v4/geocode/destinations
```
effort

實驗功能：effort 參數仍處於實驗階段。使用 /v4alpha/ 管道建立 HTTP 要求。進一步瞭解推出階段管道。

指定解析目的地查詢時要套用的處理 Effort 量 (主要影響 addressQuery 解析)：
- EFFORT_UNSPECIFIED：預設值。運作方式與 LOW 努力程度相同。
- LOW：以最快的回應時間為目標。不會對難以辨識的地址執行擴充搜尋或消除歧義。
- MEDIUM：兼顧速度和準確度。大多數要求都會以標準低延遲時間傳回。如果地址不明確或難以辨識，這項服務會進行額外處理，提高準確度，這可能需要幾秒鐘的時間。建議用於使用者可接受短暫暫停的互動式工作流程。
- HIGH：盡可能提高不完整、非正式或複雜地址的解析準確度。回覆時間可能會大幅延長。建議用於背景、批次或物流調度工作流程。
舉例來說，下列要求使用 "effort": "HIGH" 解析目的地地址查詢：
```
curl -X POST -d '{
  "addressQuery": {
    "addressQuery": "Flat 4B, Sunrise Apartments, opposite Central Mall, Andheri West, Mumbai"
  },
  "effort": "HIGH"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: *" \
https://geocode.googleapis.com/v4alpha/geocode/destinations
```
如要進一步瞭解預期延遲時間、頻率限制和建議的整合模式，請參閱「使用更精確的地理編碼」。

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

搜尋目的地要求

依地址搜尋目的地

依地點 ID 搜尋目的地

支援的地點 ID

搭配使用 Autocomplete (新版) 和 Search Destinations

依地點搜尋目的地

使用 OAuth 提出要求

搜尋目的地回應

primary

addressComponents

containingPlaces

subDestinations

entrances

structureType

navigationPoints

landmarks

arrivalSummary

parkingOptions

回覆格式

必要參數

FieldMask

選用參數

travelModes

languageCode

regionCode

placeFilter

依結構精細程度篩選

確保地址實用

effort