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

「地理編碼」一詞通常是指將清楚易懂的地址轉譯成地圖上的某個位置。而相反的過程,也就是將地圖上的某個位置轉譯成清楚易懂的地址,就稱為「反向地理編碼」

反向地理編碼要求

必要參數

  • latlng:經緯度座標,用於指定距離最近且人類可讀地址的地點。
  • key:您應用程式的 API 金鑰。為管理配額,此金鑰會識別您的應用程式。瞭解如何取得金鑰

自選參數

以下是可包含在反向地理編碼要求中的選用參數:

  • language:結果傳回時使用的語言。
    • 查看支援語言清單。Google 會經常更新支援的語言,因此這份清單可能會有遺漏。
    • 如未提供 language,地理編碼器會嘗試使用 Accept-Language 標頭中指定的偏好語言,或傳送要求的網域的原生語言。
    • 地理編碼器會盡可能提供使用者和當地居民都能讀取的街道地址。為達成此目標,系統會以當地語言傳回街道地址,並在必要時音譯為可由使用者讀取的指令碼,並觀察慣用語言。所有其他地址都會以偏好語言傳回。地址元件都是以相同語言傳回,從第一個元件中選出。
    • 如果名稱沒有偏好的語言,地理編碼器會使用最接近的值。
  • region:區碼,指定為 ccTLD (「頂層網域」) 的兩位字元值這個參數可能也會依據適用法律影響結果。
  • result_type — 一或多個地址類型的篩選器,以直立線 (|) 分隔。如果參數包含多個地址類型,API 會傳回與任何類型相符的所有地址。處理注意事項:result_type 參數不會「限制」restrict搜尋作業僅限指定的地址類型。而 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_1sublocality_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 參數不會「限制」restrict指定搜尋的位置類型。而 location_type 則是做為搜尋後篩選條件:API 會擷取指定 latlng 的所有結果,然後捨棄不符合指定位置類型的結果。可能出現的值如下:
    • "ROOFTOP" 只會傳回 Google 掌握位置資訊精確至街道地址精確度範圍的地址。
    • "RANGE_INTERPOLATED" 只會傳回所插入在兩個精確點之間 (例如十字路口) 的約略地址 (通常是在道路上)。插入的範圍通常表示街道地址無法使用屋頂地理編碼。
    • "GEOMETRIC_CENTER" 只會傳回地點的幾何中心,例如折線 (例如街道) 或多邊形 (區域)。
    • "APPROXIMATE" 只會傳回字元形式為近似的地址。

如果同時存在 result_typelocation_type 篩選器,API 只會傳回同時符合 result_typelocation_type 值的結果。如果沒有任何篩選器值可接受,API 會傳回 ZERO_RESULTS

反向地理編碼範例

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

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

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

{
   "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_typelocation_type 參數,但未包含 API 金鑰。
  • "INVALID_REQUEST" 通常表示下列其中一種狀態:
    • 缺少查詢 (addresscomponentslatlng)。
    • 指定的 result_typelocation_type 無效。
  • "UNKNOWN_ERROR" 表示伺服器發生錯誤,因此無法處理要求。如果再試一次,要求可能會成功。

反向地理編碼 Plus Codes

地理編碼回應中的 plus_code 欄位包含 Plus 代碼,以最適合查詢所查詢的經緯度。此外,在多數情況下,JSON 結果陣列會包含具有 plus_code 類型的完整地理編碼結果,以及包含 Plus 程式碼的地址。已解碼的 Plus 程式碼與要求點之間的距離保證小於 10 公尺。