本頁面由 Cloud Translation API 翻譯而成。

反向地理編碼 (地址查詢) 要求與回應

「地理編碼」一詞通常是指翻譯清晰易懂的將地址轉換成地圖上的某個位置。相反地將地圖上的某個位置轉譯成人類可讀的地址，稱為 反向地理編碼。

反向地理編碼要求

必要參數

latlng - 經緯度指定距離最近的位置人類可讀的地址
key：應用程式的 API 金鑰。這組金鑰會指出以便管理應用程式瞭解詳情取得金鑰。

選用參數

這些是可反向加入的選用參數地理編碼要求：

language — 傳回結果時使用的語言。
- 請參閱支援清單語言。Google 會經常更新支援的語言，因此這項資訊清單可能不夠詳盡。
- 如果未提供 language，地理編碼器會嘗試使用 Accept-Language 標頭或網域。
- 地理編碼器會盡可能提供使用者和當地使用者都能讀取為了達成這個目標會傳回以當地語言寫成的街道地址，然後音譯為使用者可以視需要讀取指令碼語言。其他地址都會以偏好的方式傳回語言。地址元件都會以相同的語言傳回從第一個元件中選擇
- 如果無法設定偏好的語言的名稱，地理編碼器會使用最相符的結果
region：區碼，以 ccTLD 指定 (「頂層網域」) 的兩位字元值。參數也會影響顯示比較結果。
result_type：一或多個地址類型的篩選器。並以直立線 (|) 分隔。如果參數包含多個位址類型，API 會傳回符合任一型別的所有地址。處理注意事項：result_type 參數無限制搜尋指定的地址類型。相反地 result_type 可做為搜尋後篩選器：API 會擷取所有指定 latlng 的結果，然後捨棄這些結果不符合指定的地址類型。以下是可用的值支援：
- street_address 表示精確的街道地址。
- route 表示具名道路 (例如「國道一號」)。
- intersection 表示主要的十字路口，通常有兩條主要道路交會。
- political 表示政治實體。這個類型通常表示某些行政管理區的多邊形區域。
- country 表示國家政治實體，且通常是地理編碼器所傳回的最高順位類型。
- administrative_area_level_1 表示國家/地區層級底下的第一順位行政實體。在美國境內，這類行政層級是指州。部分國家沒有這類行政層級。在大多數情況下，administrative_area_level_1 簡稱會與 ISO 3166-2 子行政區以及其他廣泛流通的清單密切相符。然而，地理編碼結果是根據多種信號和位置資料計算得出，因此我們對於結果無法做出保證。
- administrative_area_level_2 表示國家/地區層級底下的第二順位行政實體。在美國境內，這類行政層級是指郡。部分國家沒有這類行政層級。
- administrative_area_level_3 表示國家/地區層級底下的第三順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
- administrative_area_level_4 表示國家/地區層級底下的第四順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
- administrative_area_level_5 表示國家/地區層級底下的第五順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
- administrative_area_level_6 表示國家/地區層級底下的第六順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
- administrative_area_level_7 表示國家/地區層級底下的第七順位行政實體。這個類型表示小型行政單位。部分國家沒有這類行政層級。
- colloquial_area 表示實體的常用替代名稱。
- locality 表示自治城市或鄉鎮的政治實體。
- sublocality 表示縣市底下的第一順位行政實體。某些地點可能會收到以下其中一種額外類型：sublocality_level_1 到 sublocality_level_5。每個鄉鎮市區層級都是一個行政實體。數字越大表示地理區域越小。
- neighborhood 表示具名社區
- premise 表示具名地點，通常是建築物或具有共同名稱的建築物群
- subpremise 表示具名地點底下的第一順位實體，通常是具有共同名稱的建築物群中的單一建築物
- plus_code 表示經過編碼的位置參照，衍生自經緯度。對於沒有詳細地址的地點，Plus Codes 可用於取代街道地址，例如無編號的建築物或無名街道。詳情請參閱 https://plus.codes。
- postal_code 表示國家/地區郵政地址所使用的郵遞區號。
- natural_feature 表示明顯的自然地貌。
- airport 表示機場。
- park 表示具名公園。
- point_of_interest 表示具名搜尋點。一般來說，這些「搜尋點」是當地著名的實體，無法輕易歸入其他類別，例如「帝國大廈」或「艾菲爾鐵塔」。
location_type：一或多個地點類型的篩選器。並以直立線 (|) 分隔。如果參數包含多個位置類型後，API 會傳回符合任一類型的所有地址。處理注意事項：location_type 參數無限制搜尋指定的地點類型。相反地 location_type 可做為搜尋後篩選器：API 會擷取所有指定 latlng 的結果，然後捨棄這些結果不符合指定的地點類型。支援下列值：
- "ROOFTOP" 只會傳回 Google 位置資訊的精確度可縮小至街道地址。
- "RANGE_INTERPOLATED" 只會傳回反映兩精確的點 (例如十字路口)。內插範圍一般表示街道地址無法使用頂樓地理編碼。
- "GEOMETRIC_CENTER" 只會傳回幾何圖形地點的中心，例如折線 (例如街道) 或多邊形 (區域)。
- "APPROXIMATE" 只會傳回符合下列條件的位址：但大多為約略值
extra_computations：使用這個參數指定下列額外功能：
- ADDRESS_DESCRIPTORS - 請參閱位址描述元。
- BUILDING_AND_ENTRANCES - 請參閱入口和建築物輪廓，查看更多詳細資訊。
如要為同一個 API 要求啟用多項功能，請加入要求中的 extra_computations 參數、例如：
```
extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
```

如果 result_type 和 location_type 篩選器皆存在，則 API 只會傳回同時符合 result_type 和 location_type 值。如果沒有接受任何篩選器值， API 會傳回 ZERO_RESULTS。

反向地理編碼範例

以下查詢包含 Brooklyn 某個地點的經緯度值：

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

注意：請確認兩者之間沒有空格透過 latlng 傳遞時的經緯度值參數。

上述查詢會傳回下列結果：

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

請注意，反向 Geocoder 會傳回一個以上的結果。 "formatted_address" 筆搜尋結果不只是郵寄地址，但任何位置都可以使用地理命名方式。舉例來說，為某個點進行地理編碼時這個地理編碼定點可能會以街道地址表示城市 (芝加哥)、州名 (伊利諾州) 或國家/地區 (美國州別)。對 Geocoder 而言，這些都是「地址」。反向地理編碼器會傳回這些類型視為有效結果。

反向地理編碼器會比對政治實體 (國家/地區、州/省、城市和社區)、街道地址以及郵遞區號。

完整清單，所傳回 formatted_address 值如下所示

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

這個 API 會傳回不同類型的地址，系統會從最具體的較不具體的政治實體 (如社區) 和街道地址城市、郡和州/省一般來說，顯眼的結果，如本例所示。如果要只比對特定類型的地址，請參閱下方的限制顯示搜尋結果因此，相對於彼此各有不同

依類型篩選反向地理編碼

下列範例會篩選傳回的位址，僅包含那些地點類型為「ROOFTOP」，地址類型為 street_address。

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

注意：這些篩選器只適用於反向地理編碼。

反向地理編碼回應

反向地理編碼回應的格式與地理編碼回應相同回應。請參閱地理編碼回應一文。以下是反向地理編碼回應可能出現的狀態碼。

反向地理編碼狀態碼

地理編碼回應物件中的 "status" 欄位包含要求的狀態，並可能包含偵錯資訊，以協助您追蹤反向地理編碼無法運作的原因"status" 欄位可能包含的值如下：

"OK" 表示未發生任何錯誤，且至少一項地址。
"ZERO_RESULTS" 表示反向地理編碼成功，但未傳回任何結果。如果地理編碼器向遠端位置傳遞 latlng。
"OVER_QUERY_LIMIT" 表示你不在配額。
"REQUEST_DENIED" 表示要求遭拒。這可能是因為要求包含 result_type 或 location_type 參數，但不包括 API 金鑰。
"INVALID_REQUEST" 通常表示下列其中一項：
- 查詢 (address、components 或 latlng)。
- 「result_type」或「location_type」無效狀態。
"UNKNOWN_ERROR" 表示伺服器發生錯誤，因此無法處理要求。如果再試一次，要求可能會成功。

反向地理編碼 Plus Code

地理編碼回應中的 plus_code 欄位包含一個 plus code，可估算出查詢的經緯度。此外，在大多數情況下，JSON 結果陣列會包含完整地理編碼。結果為 plus_code 類型，且地址包含加號再也不是件繁重乏味的工作已解碼的 Plus Code 與要求點之間的距離保證低於 10 公尺