谷歌地圖開發：地理編碼和反地理編碼

2019-11-09 14:41:19

字體：大中小

來源：轉載

供稿：網友

谷歌地圖Geocoding說明：內容主要來自谷歌官網的文檔，谷歌地圖android api地理和反地理編碼反應遲鈍內容有時不準確，這里使用的googlemap的webapi接口。嗯，需要vpn這個不多做說明了...

什么是地理編碼？

地理編碼是將地址（如“1600 Amphitheatre Parkway, Mountain View, CA”）轉換為地理坐標（如緯度 37.423021 和經度 -122.083739）的過程，您可以借此在地圖上放置標記，或在地圖上定位。

反向地理編碼是將地理坐標轉換為可人工讀取的地址的過程。Google Maps Geocoding API 的反向地理編碼服務還可讓您找到對應于給定的地點 ID 的地址。

Google Maps Geocoding API 提供了一種通過 HTTP 請求來訪問這些服務的直接方法。

開始前的準備工作

本文檔面向需要使用其中一個 Google Maps API 提供的地圖中地理編碼數據的網站和移動開發者。

此服務通常用于對（預先知道的）靜態地址進行地理編碼，以便將應用內容放置到地圖上；例如，此服務不用于實時響應用戶輸入。有關動態地理編碼（例如，在某個用戶界面元素內）的信息，請查閱關于 Google Maps javaScript API 客戶端地理編碼器和/或 Google Play 服務 Location API 的文檔。

地理編碼是一項時間和資源密集型任務。只要有可能，請（使用此處所描述的 Google Maps Geocoding API 或其他地理編碼服務）對已知地址進行預地理編碼，并將結果存儲在您自己的設計的臨時緩存中。

要使用 Google Maps Geocoding API，您需要一個 API 密鑰。

Google Maps Geocoding API 請求格式

Google Maps Geocoding API 請求必須采用以下形式：

https://maps.googleapis.com/maps/api/geocode/output?parameters

其中，output 可以是以下值之一：

json（推薦）指示以 Javascript 對象標記 (JSON) 輸出xml 指示以 XML 格式輸出

如需通過 HTTP 訪問 Google Maps Geocoding API，請使用：

http://maps.googleapis.com/maps/api/geocode/output?parameters

對于請求中包含敏感用戶數據（例如用戶的位置）的應用，不建議使用 HTTP。

有些參數是必填的，而有些是可選的。依照 URL 的標準，參數都使用“與”字符 (&) 分隔。

Google Maps API for Work 用戶必須在其地理編碼請求中包含有效的 client 和 signature 參數。如需了解詳細信息，請參閱 Google Maps API for Work Web Services。

因為每種請求類型使用的參數不同，所以本頁面的其余部分分別介紹了地理編碼和反向地理編碼。

地理編碼（緯度/經度查詢）

地理編碼請求中的必填參數：

address – 要進行地理編碼的街道地址，采用相關國家/地區的全國郵政服務所使用的格式。應避免其他地址元素，例如企業名稱以及單元號、套房號或樓層。或 components – 您希望獲得其地理編碼的組成部分過濾器。如需了解詳細信息，請參閱組成部分過濾。如果提供了 address，還將接受組成部分過濾器作為可選參數。key – 您的應用的 API 密鑰。此密鑰可以標識您的應用，以便進行配額管理。

地理編碼請求中的可選參數：

bounds – 視口的邊框，在其中可以使地理編碼結果更顯著地發生偏向。此參數只會影響，而不會完全限制地理編碼器中的結果。（如需了解詳細信息，請參閱下面的視口偏向。）language – 返回結果時使用的語言。請參閱支持的區域語言列表。請注意，我們會經常更新支持的語言，因此，此列表可能并不全面。如果未提供 language，地理編碼器將盡可能嘗試使用發送請求區域的當地語言。region – 地區代碼，指定為一個 ccTLD（“頂級域名”）雙字符值。此參數只會影響，而不會完全限制地理編碼器中的結果。（如需了解詳細信息，請參閱下面的地區偏向。）components – 組成部分過濾器，用管道符號 (|) 分隔。每個組成部分過濾器由一個 component:value 對組成，將完全限制地理編碼器中的結果。如需了解詳細信息，請參閱下面的組成部分過濾。Supported Languages

Language Code	Language	Language Code	Language
ar	Arabic	kn	Kannada
bg	Bulgarian	ko	Korean
bn	Bengali	lt	Lithuanian
ca	Catalan	lv	Latvian
cs	Czech	ml	Malayalam
da	Danish	mr	Marathi
de	German	nl	Dutch
el	Greek	no	Norwegian
en	English	pl	Polish
en-AU	English (Australian)	pt	Portuguese
en-GB	English (Great Britain)	pt-BR	Portuguese (Brazil)
es	Spanish	pt-PT	Portuguese (Portugal)
eu	Basque	ro	Romanian
eu	Basque	ru	Russian
fa	Farsi	sk	Slovak
fi	Finnish	sl	Slovenian
fil	Filipino	sr	Serbian
fr	French	sv	Swedish
gl	Galician	ta	Tamil
gu	Gujarati	te	Telugu
hi	Hindi	th	Thai
hr	Croatian	tl	Tagalog
hu	Hungarian	tr	Turkish
id	Indonesian	uk	Ukrainian
it	Italian	vi	Vietnamese
iw	Hebrew	zh-CN	Chinese (Simplified)
ja	Japanese	zh-TW	Chinese (Traditional)

地理編碼響應

地理編碼響應以 URL 請求路徑中 output 標志指示的格式返回。

在此示例中，Google Maps Geocoding API 請求針對“1600 Amphitheatre Parkway, Mountain View, CA”查詢的 json 響應。

此請求演示了如何使用 JSON output 標志：

https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

此請求演示了如何使用 XML output 標志：

https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY

點擊下面的選項卡，查看 JSON 和 XML 響應示例。

JSONXML

{ "results" : [ { "address_components" : [ { "long_name" : "1600", "short_name" : "1600", "types" : [ "street_number" ] }, { "long_name" : "Amphitheatre Pkwy", "short_name" : "Amphitheatre Pkwy", "types" : [ "route" ] }, { "long_name" : "Mountain View", "short_name" : "Mountain View", "types" : [ "locality", "political" ] }, { "long_name" : "Santa Clara County", "short_name" : "Santa Clara County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "California", "short_name" : "CA", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] }, { "long_name" : "94043", "short_name" : "94043", "types" : [ "postal_code" ] } ], "formatted_address" : "1600 Amphitheatre Parkway, Mountain View, CA 94043, USA", "geometry" : { "location" : { "lat" : 37.4224764, "lng" : -122.0842499 }, "location_type" : "ROOFTOP", "viewport" : { "northeast" : { "lat" : 37.4238253802915, "lng" : -122.0829009197085 }, "southwest" : { "lat" : 37.4211274197085, "lng" : -122.0855988802915 } } }, "place_id" : "ChIJ2eUgeAK6j4ARbn5u_wAGqWA", "types" : [ "street_address" ] } ], "status" : "OK"}

請注意，JSON 響應包含兩個根元素：

"status" 包含請求的元數據。請參閱下面的狀態代碼。"results" 包含一個有關地理編碼地址信息和幾何信息的數組。

雖然當地址查詢比較模糊時，地理編碼器可能返回多個結果，但通常地址查找只返回 "results" 數組中的一個條目。

請注意，如果您想從結果中提取值，通常需要對這些結果進行解析。JSON 的解析相對容易。如需了解一些推薦的設計模式，請參閱解析 JSON。

狀態代碼

地理編碼響應對象中的 "status" 字段包含了請求的狀態，還可能包含調試信息，以幫助您查明地理編碼不工作的原因。"status" 字段可以包含以下值：

"OK" 表示未出現任何錯誤；已成功解析地址，并且至少返回了一個地理編碼。"ZERO_RESULTS" 表示地理編碼成功，但未返回任何結果。如果向地理編碼器傳遞了一個不存在 address，就可能會發生這種情況。"OVER_QUERY_LIMIT" 表示您已超出配額。"REQUEST_DENIED" 表示系統已拒絕您的請求。"INVALID_REQUEST" 一般表示缺少查詢（address、components 或 latlng）。"UNKNOWN_ERROR" 表示由于服務器發生錯誤，因此無法處理該請求。如果您重試一次，請求可能會成功

錯誤消息

當地理編碼器返回 OK 以外的狀態代碼時，地理編碼響應對象中可能會包含一個附加的 error_message 字段。此字段更詳細地說明了給定狀態代碼背后的原因。

注：此字段不保證始終出現，并且其內容可能會更改。

結果

當地理編碼器返回結果時，會將這些結果放在一個 (JSON) results 數組中。即使地理編碼器沒有返回任何結果（例如，如果地址不存在），它仍然會返回一個空的 results 數組。（XML 響應包含零個或更多個 <result> 元素。）

典型的結果由以下字段組成：

types[] 數組表示返回結果的類型。此數組包含一組標記（可能為零個或多個），用于標識結果中所返回特征的類型。例如，“芝加哥”的地理編碼返回“locality”，這表明“芝加哥”是一個城市，并且還返回“political”，這表明它是一個政治實體。

formatted_address：是一個包含此位置可人工讀取的地址的字符串。通常此地址相當于“郵政地址”，有時會因國家/地區而異。（請注意，由于許可限制，某些國家（如英國）不允許發布真實的郵政地址。）此地址通常由一個或多個地址組成部分組成。例如，地址“111 8th Avenue, New York, NY”包含以下地址組成部分：“111”（街道號）、“8th Avenue”（道路）、“New York”（城市）和“NY”（美國的一個州）。這些地址組成部分包含如下所述的附加信息。

address_components[] 是包含獨立的地址組成部分的數組，如上所述。通常，每個 address_component 均包含：

types[]，一個表示地址組成部分類型的數組。long_name 是地理編碼器返回的地址組成部分的完整文本說明或名稱。short_name 是地址組成部分的文本名稱縮寫（如有）。例如，Alaska 州的地址組成部分可以有 long_name“Alaska”和 short_name“AK”（使用雙字母郵政縮寫表示）。

請注意，address_components[] 中包含的地址組成部分可能比 formatted_address 中記錄的更多。

postcode_localities[] 是一個數組，表示一個郵政編碼中包含的所有地方。只有當結果是一個包含多個地方的郵政編碼時，才會有此數組。

geometry 包含以下信息：

location：其中包含地理編碼經度、緯度值。對于普通的地址查找，此字段通常是最重要的。

location_type 存儲有關指定位置的附加數據。目前支持以下值：

"ROOFTOP" 表示返回的結果是一個精確的地理編碼，我們使其位置信息精確到街道地址的精度。"RANGE_INTERPOLATED" 表示返回的結果反映了兩個精確點（例如交叉路口）之間用內插法計算得到的近似值（通常在道路上）。當某個街道地址的 rooftop 地理編碼不可用時，通常會返回內插值結果。"GEOMETRIC_CENTER" 表示返回的結果是某個位置（如多段線（例如街道）或多邊形（地區））的幾何中心。"APPROXIMATE" 表示返回的結果是近似值。viewport 包含用于顯示返回結果的推薦視口，指定為兩個緯度、經度值，分別定義視口邊框的 southwest 和 northeast 角。視口通常用來在向用戶顯示結果時為該結果加邊框。bounds（可選返回）存儲可完全包含返回結果的邊框。請注意，這些邊界可能與推薦的視口不一致。（例如，舊金山包含費拉隆島，理論上它是這個城市的一部分，但可能不應該在視口中返回。）

partial_match 表示雖然地理編碼器能夠匹配所請求的地址的一部分，但它未能返回原始請求的精確匹配項。您不妨檢查一下原始請求中是否有拼寫錯誤和/或地址不完整的情況。

對于請求中所傳遞的行政區劃內不存在的街道地址，最常發生部分匹配的情況。當請求與同一行政區劃中的兩個或更多位置相匹配時，也可能會返回部分匹配。例如，“21 Henr St, Bristol, UK”將返回 Henry Street 和 Henrietta Street 這兩項部分匹配結果。請注意，如果請求中包含拼寫錯誤的地址組成部分，地理編碼服務可能會建議一個備選地址。以這種方式觸發的建議也將標記為部分匹配。

place_id 是唯一一個可以與其他 Google API 結合使用的標識符。例如，您可以在 Google Places API 請求中使用 place_id 獲取當地企業的詳情，如電話號碼、營業時間、用戶評論等。請參閱地點 ID 概覽。

由于不能保證對 Google Maps Geocoding API 請求的個別響應的格式準確，因此您永遠不應該假定元素處于絕對位置。（特別是，Geocoding API 響應中 address_components 的數量會根據請求的地址而有所不同，并且可以隨時間而改變。）相反，您應該解析響應，并通過表達式選擇合適的值。如需了解詳細信息，請參閱解析 Web 服務響應。

地址類型和地址組成部分類型

結果中的 types[] 數組表示地址類型。地址類型的示例包括街道地址、國家/地區或政治實體。在 address_components[] 中也有一個 types[] 數組，用來表示地址各個部分的類型。示例包括門牌號碼或國家/地區。（以下是類型的完整列表。）地址可能有多種類型。這些類型可能會被視為“標記”。例如，許多城市都標有 political 和 locality 類型。

地理編碼器以地址類型和地址組成部分類型數組這兩種形式支持并返回以下類型：

street_address 表示精確的街道地址。route：表示已命名的路線（例如“US 101”）intersection：表示主要交叉路口，通常是兩條主要道路的交叉路口political：表示政治實體。通常，這種類型表示某個民政管理部門的多邊形country：表示國家政治實體，通常是由地理編碼器返回的最高級別類型administrative_area_level_1：表示國家/地區級別以下的一級行政實體。在美國，這種行政級別就是州。并非所有國家都設有這類行政級別administrative_area_level_2：表示國家/地區級別以下的二級行政實體。在美國，這種行政級別就是縣。并非所有國家都設有這類行政級別administrative_area_level_3：表示國家/地區級別以下的三級行政實體。此類型表示較小的行政區劃單位。并非所有國家都設有這類行政級別administrative_area_level_4：表示國家/地區級別以下的四級行政實體。此類型表示較小的行政區劃單位。并非所有國家都設有這類行政級別administrative_area_level_5：表示國家/地區級別以下的五級行政實體。此類型表示較小的行政區劃單位。并非所有國家都設有這類行政級別colloquial_area：表示實體的常用替代名稱locality 表示合并的城市或城鎮政治實體。ward 表示一種特定的日本行政區劃類型，以便于區分某個日本地址中的多個行政區劃組成部分。sublocality：表示 locality 以下的一級行政實體。某些位置可能會收到其他類型之一：從 sublocality_level_1 到 sublocality_level_5。每個 sublocality 級別都是一個行政實體。數字越大，表示的地理區域越小neighborhood 表示已命名的街區premise 表示已命名的位置，通常是具有常見名稱的一棟或一群建筑物subpremise 表示指定位置以下的一級實體，通常是同名建筑群中的單個建筑物postal_code 表示郵政編碼，用于國內的地址郵寄。natural_feature：表示著名的自然景觀airport：表示機場park：表示已命名的公園。point_of_interest 表示已命名的景點。通常，這些“景點”是不容易歸入其他類別的著名地方實體，如“帝國大廈”或“自由女神像”。

空的類型列表表示特殊的地址組成部分沒有對應的已知類型，例如法國的地方 (Lieu-dit)。

除了上述類型之外，地址組成部分還可能包括下列類型。

注：此列表并不全面，并且隨時可能更改。

floor：表示某個建筑物地址的樓層establishment 通常表示某個尚未歸類的地方。point_of_interest 表示已命名的景點。parking 表示停車場或停車設施。post_box 表示特定的郵政信箱。postal_town 表示地理區域的分組，如 locality 和 sublocality，在某些國家/地區用于郵寄地址。room 表示某個建筑物地址的房間。street_number 表示確切的門牌號碼。bus_station、train_station 和 transit_station 表示巴士、火車或公交車站的位置。

視口偏向

在地理編碼請求中，您可以指示讓地理編碼服務傾向于使用某個給定視口（表示為邊框）中的結果。您可以通過設置 bounds 參數在請求 URL 中執行此操作。請注意，偏向只是傾向于使用邊界以內的結果；如果在這些邊界之外存在更相關的結果，也可能會將這些結果包括在內。

bounds 參數定義了此邊框的西南角和東北角的緯度/經度坐標，并使用管道字符 (|) 分隔這些坐標。

例如，“溫內特卡”的地理編碼一般會返回芝加哥的以下郊區：

請求：

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&key=YOUR_API_KEY

響應：

{ "results" : [ { "address_components" : [ { "long_name" : "Winnetka", "short_name" : "Winnetka", "types" : [ "locality", "political" ] }, { "long_name" : "New Trier", "short_name" : "New Trier", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Cook County", "short_name" : "Cook County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Illinois", "short_name" : "IL", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Winnetka, IL, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 42.1282269, "lng" : -87.7108162 }, "southwest" : { "lat" : 42.0886089, "lng" : -87.7708629 } }, "location" : { "lat" : 42.10808340000001, "lng" : -87.735895 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 42.1282269, "lng" : -87.7108162 }, "southwest" : { "lat" : 42.0886089, "lng" : -87.7708629 } } }, "place_id" : "ChIJW8Va5TnED4gRY91Ng47qy3Q", "types" : [ "locality", "political" ] } ], "status" : "OK"}

然而，添加一個為洛杉磯圣費爾南多谷定義邊框的 bounds 參數會使得此地理編碼返回位于該位置的名為“溫內特卡”的鄰近地區：

請求：

https://maps.googleapis.com/maps/api/geocode/json?address=Winnetka&bounds=34.172684,-118.604794|34.236144,-118.500938&key=YOUR_API_KEY

響應：

{ "results" : [ { "address_components" : [ { "long_name" : "Winnetka", "short_name" : "Winnetka", "types" : [ "neighborhood", "political" ] }, { "long_name" : "Los Angeles", "short_name" : "LA", "types" : [ "locality", "political" ] }, { "long_name" : "Los Angeles County", "short_name" : "Los Angeles County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "California", "short_name" : "CA", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Winnetka, Los Angeles, CA, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 34.2355209, "lng" : -118.5534191 }, "southwest" : { "lat" : 34.1854649, "lng" : -118.588536 } }, "location" : { "lat" : 34.2048586, "lng" : -118.5739621 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 34.2355209, "lng" : -118.5534191 }, "southwest" : { "lat" : 34.1854649, "lng" : -118.588536 } } }, "place_id" : "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ", "types" : [ "neighborhood", "political" ] } ], "status" : "OK"}

地區偏向

在地理編碼響應中，Google Maps Geocoding API 返回受發送請求地區（通常是國家）影響的地址結果。例如，在美國的某個區域和在西班牙搜索“San Francisco”，可能會返回不同的結果。

您可以使用 region 參數將 Google Maps Geocoding API 設置為返回偏向于特定地區的結果。該參數帶有指定地區偏向的 ccTLD（國家代碼頂級域）自變量。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些明顯的例外。例如，英國的國家代碼頂級域名為“uk”(.co.uk)，而其 ISO 3166-1 代碼卻是“gb”（專指“大不列顛及北愛爾蘭聯合王國”這一實體）。

地理編碼結果可以偏向于正式推出了主要 Google Maps 應用的每個區域。請注意，偏向只是傾向于使用某個特定區域的結果；如果在此區域以外存在更相關的結果，也可能會將這些結果包括在內。

例如，由于 Google Maps Geocoding API 的默認區域設置為美國，因此“Toledo”的地理編碼返回以下結果。請求：

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY

響應：

{ "results" : [ { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Lucas County", "short_name" : "Lucas County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Ohio", "short_name" : "OH", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Toledo, OH, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 41.732844, "lng" : -83.4547053 }, "southwest" : { "lat" : 41.580266, "lng" : -83.69423700000002 } }, "location" : { "lat" : 41.6639383, "lng" : -83.55521200000001 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 41.732844, "lng" : -83.4547053 }, "southwest" : { "lat" : 41.580266, "lng" : -83.69423700000002 } } }, "place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw", "types" : [ "locality", "political" ] }, { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Lincoln County", "short_name" : "Lincoln County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Oregon", "short_name" : "OR", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Toledo, OR, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 44.6383219, "lng" : -123.9129439 }, "southwest" : { "lat" : 44.598776, "lng" : -123.954585 } }, "location" : { "lat" : 44.621507, "lng" : -123.9384478 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 44.6383219, "lng" : -123.9129439 }, "southwest" : { "lat" : 44.598776, "lng" : -123.954585 } } }, "place_id" : "ChIJmcjO1AjUwVQRDsRYrfWvzyo", "types" : [ "locality", "political" ] }, { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Tama County", "short_name" : "Tama County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Iowa", "short_name" : "IA", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Toledo, IA, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 42.00388600000001, "lng" : -92.56695289999999 }, "southwest" : { "lat" : 41.9784431, "lng" : -92.60007299999999 } }, "location" : { "lat" : 41.9972134, "lng" : -92.5835266 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 42.00388600000001, "lng" : -92.56695289999999 }, "southwest" : { "lat" : 41.9784431, "lng" : -92.60007299999999 } } }, "place_id" : "ChIJvwoVNEOE74cR3oQfIk7m6fU", "types" : [ "locality", "political" ] }, { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Lewis County", "short_name" : "Lewis County", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Washington", "short_name" : "WA", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] }, { "long_name" : "98591", "short_name" : "98591", "types" : [ "postal_code" ] } ], "formatted_address" : "Toledo, WA 98591, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 46.44799889999999, "lng" : -122.8419249 }, "southwest" : { "lat" : 46.43233009999999, "lng" : -122.85575 } }, "location" : { "lat" : 46.4398305, "lng" : -122.846783 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 46.44799889999999, "lng" : -122.8419249 }, "southwest" : { "lat" : 46.43233009999999, "lng" : -122.85575 } } }, "place_id" : "ChIJPw9m6cb4k1QRyA5L3wI_dRM", "types" : [ "locality", "political" ] } ], "status" : "OK"}

設置了 region=es（西班牙）后，“Toledo”的地理編碼請求將返回西班牙的城市。請求：

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=es&key=YOUR_API_KEY

響應：

{ "results" : [ { "address_components" : [ { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "locality", "political" ] }, { "long_name" : "Toledo", "short_name" : "Toledo", "types" : [ "administrative_area_level_4", "political" ] }, { "long_name" : "Vega de Toledo", "short_name" : "Vega de Toledo", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Toledo", "short_name" : "TO", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Castile-La Mancha", "short_name" : "CM", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Spain", "short_name" : "ES", "types" : [ "country", "political" ] } ], "formatted_address" : "Toledo, Toledo, Spain", "geometry" : { "bounds" : { "northeast" : { "lat" : 39.88605099999999, "lng" : -3.9192423 }, "southwest" : { "lat" : 39.8383676, "lng" : -4.0629256 } }, "location" : { "lat" : 39.8628316, "lng" : -4.027323099999999 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 39.88605099999999, "lng" : -3.9192423 }, "southwest" : { "lat" : 39.8383676, "lng" : -4.0629256 } } }, "place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y", "types" : [ "locality", "political" ] } ], "status" : "OK"}

組成部分過濾

在地理編碼響應中，Google Maps Geocoding API 可以返回限制在某個特定區域的地址結果。使用 components 過濾器來指定限制。過濾器由一個 component:value 對列表組成，這些鍵值對用管道符號 (|) 分隔。只有符合所有過濾器的結果才會被返回。過濾器值支持與其他地理編碼請求相同的用于拼寫校正和部分匹配的方法。如果地理編碼結果部分匹配某個組成部分過濾器，它將在響應中包含 partial_match 字段。

可以過濾的 components 包括：

route 用來匹配路由的長名稱或短名稱。locality 既可以匹配 locality 類型，也可以匹配 sublocality 類型。administrative_area 用來匹配所有 administrative_area 級別。postal_code 用來匹配 postal_code 和 postal_code_prefix。country 用來匹配國家/地區名稱或兩個字母的 ISO 3166-1 國家/地區代碼。

注：要么在地址參數中指定每個地址組成部分，要么將其指定為組成部分過濾器，這兩種方式只能選擇其一，不可同時使用。這樣做可能會導致 ZERO_RESULTS。

設置了 components=country:ES 后，“Santa Cruz”的地理編碼將返回西班牙加那利群島的圣克魯斯特內里費。請求：

https://maps.googleapis.com/maps/api/geocode/json?address=santa+cruz&components=country:ES&key=YOUR_API_KEY

響應：

{ "results" : [ { "address_components" : [ { "long_name" : "Santa Cruz de Tenerife", "short_name" : "Santa Cruz de Tenerife", "types" : [ "locality", "political" ] }, { "long_name" : "Santa Cruz de Tenerife", "short_name" : "Santa Cruz de Tenerife", "types" : [ "administrative_area_level_4", "political" ] }, { "long_name" : "Anaga", "short_name" : "Anaga", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Santa Cruz de Tenerife", "short_name" : "TF", "types" : [ "administrative_area_level_2", "political" ] }, { "long_name" : "Canarias", "short_name" : "CN", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "Spain", "short_name" : "ES", "types" : [ "country", "political" ] } ], "formatted_address" : "Santa Cruz de Tenerife, Santa Cruz de Tenerife, Spain", "geometry" : { "bounds" : { "northeast" : { "lat" : 28.487616, "lng" : -16.2356646 }, "southwest" : { "lat" : 28.4280248, "lng" : -16.3370045 } }, "location" : { "lat" : 28.4636296, "lng" : -16.2518467 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 28.487616, "lng" : -16.2356646 }, "southwest" : { "lat" : 28.4280248, "lng" : -16.3370045 } } }, "place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM", "types" : [ "locality", "political" ] } ], "status" : "OK"}

包含組成部分過濾器的查詢將只返回匹配該過濾器的地理編碼結果。如果沒有找到匹配項，地理編碼器會返回一個與該過濾器本身相匹配的結果。請求：

https://maps.googleapis.com/maps/api/geocode/json?address=Torun&components=administrative_area:TX|country:US&key=YOUR_API_KEY

響應：

{ "results" : [ { "address_components" : [ { "long_name" : "Texas", "short_name" : "TX", "types" : [ "administrative_area_level_1", "political" ] }, { "long_name" : "United States", "short_name" : "US", "types" : [ "country", "political" ] } ], "formatted_address" : "Texas, USA", "geometry" : { "bounds" : { "northeast" : { "lat" : 36.5007041, "lng" : -93.5080389 }, "southwest" : { "lat" : 25.8371638, "lng" : -106.6456461 } }, "location" : { "lat" : 31.9685988, "lng" : -99.9018131 }, "location_type" : "APPROXIMATE", "viewport" : { "northeast" : { "lat" : 36.5015087, "lng" : -93.5080389 }, "southwest" : { "lat" : 25.8371638, "lng" : -106.6456461 } } }, "partial_match" : true, "place_id" : "ChIJSTKCCzZwQIYRPN4IGI8c6xY", "types" : [ "administrative_area_level_1", "political" ] } ], "status" : "OK"}

只有當您提供的過濾器相互排斥時，組成部分過濾才會返回 ZERO_RESULTS 響應。請求：

https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY

響應：

{ "results" : [], "status" : "ZERO_RESULTS"}

使用 components 過濾器時，可以在無地址參數的情況下進行查詢，但不能在沒有值的情況下指定組成部分。請求：

https://maps.googleapis.com/maps/api/geocode/json?components=route:Annegatan|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY

響應：

{ "results" : [ { "address_components" : [ { "long_name" : "Annegatan", "short_name" : "Annegatan", "types" : [ "route" ] }, { "long_name" : "Helsingfors", "short_name" : "Helsingfors", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Finland", "short_name" : "FI", "types" : [ "country", "political" ] } ], "formatted_address" : "Annegatan, Helsingfors, Finland", "geometry" : { "bounds" : { "northeast" : { "lat" : 60.168997, "lng" : 24.9427959 }, "southwest" : { "lat" : 60.1626627, "lng" : 24.934 } }, "location" : { "lat" : 60.1657808, "lng" : 24.938451 }, "location_type" : "GEOMETRIC_CENTER", "viewport" : { "northeast" : { "lat" : 60.168997, "lng" : 24.9427959 }, "southwest" : { "lat" : 60.1626627, "lng" : 24.934 } } }, "place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM", "types" : [ "route" ] }, { "address_components" : [ { "long_name" : "Annev?gen", "short_name" : "Annev?gen", "types" : [ "route" ] }, { "long_name" : "Vanda", "short_name" : "Vanda", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Finland", "short_name" : "FI", "types" : [ "country", "political" ] }, { "long_name" : "01420", "short_name" : "01420", "types" : [ "postal_code" ] } ], "formatted_address" : "Annev?gen, 01420 Vanda, Finland", "geometry" : { "bounds" : { "northeast" : { "lat" : 60.3282738, "lng" : 25.1162163 }, "southwest" : { "lat" : 60.32564009999999, "lng" : 25.1076474 } }, "location" : { "lat" : 60.3271069, "lng" : 25.1118046 }, "location_type" : "GEOMETRIC_CENTER", "viewport" : { "northeast" : { "lat" : 60.3283059302915, "lng" : 25.1162163 }, "southwest" : { "lat" : 60.32560796970849, "lng" : 25.1076474 } } }, "partial_match" : true, "place_id" : "ChIJ3UJCNt4GkkYR8-_a8Dh25kA", "types" : [ "route" ] }, { "address_components" : [ { "long_name" : "Anneplatsen", "short_name" : "Anneplatsen", "types" : [ "route" ] }, { "long_name" : "Helsingfors", "short_name" : "Helsingfors", "types" : [ "administrative_area_level_3", "political" ] }, { "long_name" : "Finland", "short_name" : "FI", "types" : [ "country", "political" ] }, { "long_name" : "00100", "short_name" : "00100", "types" : [ "postal_code" ] } ], "formatted_address" : "Anneplatsen, 00100 Helsingfors, Finland", "geometry" : { "bounds" : { "northeast" : { "lat" : 60.1695664, "lng" : 24.9357125 }, "southwest" : { "lat" : 60.168997, "lng" : 24.934 } }, "location" : { "lat" : 60.1692741, "lng" : 24.9348016 }, "location_type" : "GEOMETRIC_CENTER", "viewport" : { "northeast" : { "lat" : 60.17063068029151, "lng" : 24.9362052302915 }, "southwest" : { "lat" : 60.1679327197085, "lng" : 24.9335072697085 } } }, "partial_match" : true, "place_id" : "ChIJeahMqswLkkYR2vQfG1nHI3M", "types" : [ "route" ] } ], "status" : "OK"}

反向地理編碼（地址查找）

術語地理編碼一般是指將可人工讀取的地址轉換為地圖上的某個位置。與之相反，將地圖上的某個位置轉換為可人工讀取的地址的過程，就稱為反向地理編碼。

必填參數：您必須在反向地理編碼請求中提供下列參數之一，但不可同時提供這兩個參數：

要么：latlng – 經緯度值，用于指定希望獲得其最接近的、可人工讀取的地址的位置。或者：place_id – 您希望獲得其可人工讀取的地址的地方的地點 ID。地點 ID 是唯一一個可以與其他 Google API 結合使用的標識符。例如，您可以使用由 Google Maps Roads API 返回的 placeID 來獲取某個拍攝點的地址。如需了解有關地點 ID 的詳細信息，請參閱地點 ID 概覽。只有當請求包括 API 密鑰或 Google Maps API for Work 客戶端 ID 時，才能指定地點 ID。

反向地理編碼請求中的可選參數：

您可以將下列可選參數包括在反向地理編碼請求中：

key – 您的應用的 API 密鑰，可從 Google API Console 獲得。此密鑰可以標識您的應用，以便進行配額管理。language – 返回結果時使用的語言。請參閱支持的區域語言列表。請注意，我們會經常更新支持的語言，因此，此列表可能并不全面。如果未提供 language，地理編碼器將盡可能嘗試使用發送請求區域的當地語言。result_type – 一個或多個地址類型，用管道符號 (|) 分隔。地址類型的示例：country、street_address、postal_code。如需查看允許值的完整列表，請參閱此頁面上的地址類型。如果指定了一種類型，會將結果限制于這種類型。如果指定了多種類型，該 API 將返回匹配其中任何類型的所有地址。注：此參數僅適用于包括 API 密鑰或客戶端 ID 的請求。location_type – 一個或多個位置類型，用管道符號 (|) 分隔。如果指定了一種類型，會將結果限制于這種類型。如果指定了多種類型，該 API 將返回匹配其中任何類型的所有地址。注：此參數僅適用于包括 API 密鑰或客戶端 ID 的請求。可支持以下值："ROOFTOP" 將結果限制為我們使其位置信息精確到街道地址精度的地址。"RANGE_INTERPOLATED" 將結果限制為反映了兩個精確點（例如交叉路口）之間用內插法計算得到的近似值（通常在道路上）的地址。內插的范圍通常表示某個街道地址的 rooftop 地理編碼不可用。"GEOMETRIC_CENTER" 將結果限制為某個位置（如多段線（例如街道）或多邊形（地區））的幾何中心。"APPROXIMATE" 將結果限制為是近似值的地址。

如果 result_type 和 location_type 限制同時存在，那么該 API 將只返回同時匹配 result_type和 location_type 限制的結果。

緯度/經度的反向地理編碼

以下查詢包含了布魯克林某個位置的緯度/經度值：

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 results[] ...

請注意，反向地理編碼器返回了多個結果。"formatted_address" 的結果不僅有郵政地址，還包括對某個位置的任何地理命名方式。例如，對芝加哥市的某個點進行地理編碼時，地理編碼的點可以表示為街道地址、城市（芝加哥）、所在州（伊利諾伊州）或國家/地區（美國）。所有這些都是地理編碼器的“地址”。反向地理編碼器返回這些類型中的任何一種作為有效結果。

反向地理編碼器會匹配政治實體（國家/地區、省、市和街區）、街道地址及郵政編碼。

由以前的查詢返回的 formatted_address 值的完整列表如下所示。

"formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA","formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11211, USA","formatted_address" : "Grand St/Bedford Av, Brooklyn, NY 11249, USA","formatted_address" : "Bedford Av/Grand St, Brooklyn, NY 11211, USA","formatted_address" : "Brooklyn, NY 11211, USA","formatted_address" : "Williamsburg, Brooklyn, NY, USA","formatted_address" : "Brooklyn, NY, USA","formatted_address" : "New York, NY, USA","formatted_address" : "New York, USA","formatted_address" : "United States",

通常，返回的地址按精確度從最具體到最不具體的順序排列；正如本例中所示，最準確的地址在結果中擺在最突出的位置。請注意，我們會返回不同類型的地址，從最具體的街道地址到不那么具體的政治實體，如街區、市、縣、州等。如果您想匹配特定類型的地址，請參閱以下有關按類型限制結果的部分。

注：反向地理編碼是一種估計。地理編碼器將嘗試在某一誤差限度范圍內查找最接近的可尋址位置。如果沒有找到匹配項，地理編碼器會返回零個結果。

地點 ID 的反向地理編碼

以下查詢包含了布魯克林某個位置的地點 ID：

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJd8BlQ2BZwokRAFUEcm_qrcA&key=YOUR_API_KEY

上述查詢返回以下結果：

{ "results" : [ { "address_components" : [ { "long_name" : "277", "short_name" : "277", "types" : [ "street_number" ] }, { "long_name" : "Bedford Ave", "short_name" : "Bedford Ave", "types" : [ "route" ] }, { "long_name" : "Williamsburg", "short_name" : "Williamsburg", "types" : [ "neighborhood", "political" ] }, { "long_name" : "Brooklyn", "short_name" : "Brooklyn", "types" : [ "sublocality_level_1", "sublocality", "political" ] }, { "long_name" : "Kings County", "short_name" : "Kings County", "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 Ave, 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 } } }, "partial_match" : true, "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA", "types" : [ "street_address" ] } ], "status" : "OK"}

受類型限制的反向地理編碼

以下示例將返回的地址限制為位置類型是 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 密鑰或客戶端 ID。"INVALID_REQUEST" 通常表示下列情況之一：缺少查詢（address、components 或 latlng）。提供的 result_type 或 location_type 無效。"UNKNOWN_ERROR" 表示由于服務器發生錯誤，因此無法處理該請求。如果您重試一次，請求可能會成功