「地理編碼」一詞通常是指將使用者可理解的地址轉譯為地圖上的位置。相反地，在地圖上將位置轉譯成人類可讀的地址，就是所謂的反向地理編碼。
反向地理編碼要求
必要參數
latlng— 指定想要以最接近人類可讀地址的位置的經緯度座標。key：應用程式的 API 金鑰。此金鑰會識別您的應用程式，用於管理配額。瞭解如何取得金鑰。
選用參數
以下提供幾個選用參數，您可以用來進行反向地理編碼要求：
language：傳回結果的語言。- 請參閱支援的語言清單。Google 會經常更新支援的語言，因此這份清單可能不夠詳盡。
- 如未提供
language，地理編碼器會嘗試使用Accept-Language標頭中指定的偏好語言，或要求傳送所在網域的原生語言。 - 地理編碼器會盡可能提供使用者以及當地使用者都能理解的街道地址。為達成這個目標，系統會傳回採用當地語言的街道地址，並在需要時轉譯成可供使用者理解的指令碼，並觀察採用偏好語言。所有其他地址都會以偏好語言傳回。地址元件均以相同語言傳回，且從第一個元件選擇。
- 如果名稱沒有您偏好的語言，地理編碼器就會使用最接近的比對語言。
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"只會傳回字元為約略地址的地址。
如果同時有 result_type 和 location_type 篩選器，API 只會傳回符合 result_type 和 location_type 值的結果。如果不接受任何篩選值，API 會傳回 ZERO_RESULTS。
反向地理編碼的範例
以下查詢包含布魯克林某個地點的經緯度值：
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_type或location_type參數，但沒有 API 金鑰。"INVALID_REQUEST"通常表示下列其中一項：- 查詢 (
address、components或latlng) 遺失。 - 指定的
result_type或location_type無效。
- 查詢 (
"UNKNOWN_ERROR"表示伺服器發生錯誤，因此無法處理要求。如果再試一次，要求可能會成功。
反向地理編碼加上代碼
地理編碼回應中的 plus_code 欄位包含加號，其中最能精確找出查詢的經緯度。此外，在大多數情況下，JSON 結果陣列包含 plus_code 類型的完整地理編碼結果，以及含有 Plus 代碼的地址。經過解碼的 Plus Code 與要求點之間的距離保證不超過 10 公尺。