「地理編碼」一詞通常是指翻譯清晰易懂的 將地址轉換成地圖上的某個位置。相反地 將地圖上的某個位置轉譯成人類可讀的地址,稱為 反向地理編碼。
反向地理編碼要求
必要參數
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
:使用這個參數指定 下列額外功能: ,瞭解如何調查及移除這項存取權。 如要為同一個 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
上述查詢會傳回下列結果:
{
"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 公尺