要求
Geocoding API 要求使用以下格式：
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
其中 outputFormat 可以是下列其中一個值：
json(建議) 代表 JavaScript 物件標記法 (JSON) 中的輸出內容；或xml代表 XML 中的輸出
使用 API 金鑰的要求必須透過 HTTPS 傳送。
有些參數為必要，而有些參數則為選用。如同網址的標準，參數會以 & 符號 (&) 字元分隔。
本頁的其餘部分會分別說明地理編碼和反向地理編碼，因為每種要求都有不同的參數。
地理編碼 (緯度/經度查詢) 參數
地理編碼要求的必要參數：
address：您要進行地理編碼的街道地址或「plus code」。按照相關國家/地區郵政服務使用的格式來指定地址。請避免使用其他地址元素，例如商家名稱和單位、套房或樓層號碼。街道地址元素應以空格分隔 (此處以網址逸出為%20)：address=24%20Sussex%20Drive%20Ottawa%20ON
請按照這裡所示的格式來設定加號格式 (加號在網址中逸出為%2B，空格則逸出為%20)：- 全球代碼是 4 個字元的區碼，加上 6 個字元以上的地區代碼 (例如 849VCWC8+R9 為
849VCWC8%2BR9)。 - 複合代碼是 6 個字元以上的地區代碼，加上明確的位置 (例如 CWC8+R9 Mountain View, CA, USA 為
CWC8%2BR9%20Mountain%20View%20CA%20USA)。
--OR--
components— 以直立線字元 (|) 分隔的元素的元件篩選器。如果提供address，也接受這個元件篩選器做為選用參數。 元件篩選器中的每個元素都包含一個component:value組合，並完全限制地理編碼器的結果。如要進一步瞭解元件篩選，請參閱下方說明。- 全球代碼是 4 個字元的區碼，加上 6 個字元以上的地區代碼 (例如 849VCWC8+R9 為
key：應用程式的 API 金鑰。此金鑰會識別您的應用程式，用於管理配額。瞭解如何取得金鑰。
如需其他指引，請參閱常見問題。
地理編碼要求中的選用參數：
bounds— 可視區域的定界框，用來更精確地調整地理編碼結果。這個參數只會影響 定位器的結果，而非完全限制。(詳情請參閱下方的可視區域自訂調整)。language：傳回結果的語言。- 請參閱支援的語言清單。Google 會經常更新支援的語言，因此這份清單可能不夠詳盡。
- 如未提供
language，地理編碼器會嘗試使用Accept-Language標頭中指定的偏好語言，或要求傳送所在網域的原生語言。 - 地理編碼器會盡可能提供使用者以及當地使用者都能理解的街道地址。為達成這個目標，系統會傳回採用當地語言的街道地址，並在需要時轉譯成可供使用者理解的指令碼，並觀察採用偏好語言。所有其他地址都會以偏好語言傳回。地址元件均以相同語言傳回，且從第一個元件選擇。
- 如果名稱沒有您偏好的語言，地理編碼器就會使用最接近的比對語言。
- 偏好語言對 API 選擇傳回的結果集和其傳回順序的影響較小。地理編碼器會以不同的語言解讀縮寫，例如街道類型的縮寫，或是可能在某種語言中有效但其他語言的同義詞。舉例來說，utca 和 tér 分別是匈牙利街道和正方形的同義詞。
region：以 ccTLD (「頂層網域」) 為兩個字元的值來指定區域代碼。這個參數只會影響 定位器結果，而非完全限制。(詳情請參閱下方的區域自訂調整)。這個參數也可能會根據適用的法律影響結果。components：元件篩選器，以直立線 (|) 分隔。如果要求中不含address，篩選器即為元件篩選器。元件篩選器中的每個元素都包含一個component:value組合，並完全限制地理編碼器的結果。如要進一步瞭解元件篩選，請參閱下方說明。
回應
地理編碼回應會以網址要求中的 output 標記表示格式，或者根據預設傳回 JSON 格式。
在這個範例中，Geocoding API 會針對地點 ID「ChIJeRpOeF67j4AR9ydy_PIzPuM」的查詢要求 json 回應。這個地點的 ID 是地址為 1600 Amphitheatre Parkway, Mountain View, CA
此要求示範如何使用 JSON output 標記：
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
此要求示範如何使用 XML output 旗標：
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
選取以下分頁標籤，即可查看 JSON 和 XML 回應範例。
JSON
{
"results": [
{
"address_components": [
{
"long_name": "1600",
"short_name": "1600",
"types": [
"street_number"
]
},
{
"long_name": "Amphitheatre Parkway",
"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 Pkwy, Mountain View, CA 94043, USA",
"geometry": {
"location": {
"lat": 37.4224428,
"lng": -122.0842467
},
"location_type": "ROOFTOP",
"viewport": {
"northeast": {
"lat": 37.4239627802915,
"lng": -122.0829089197085
},
"southwest": {
"lat": 37.4212648197085,
"lng": -122.0856068802915
}
}
},
"place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM",
"plus_code": {
"compound_code": "CWC8+X8 Mountain View, CA",
"global_code": "849VCWC8+X8"
},
"types": [
"street_address"
]
}
],
"status": "OK"
}
請注意，JSON 回應包含兩個根元素：
"status"包含要求的中繼資料。請參閱下方的狀態碼。"results"包含地理編碼地址資訊和幾何圖形資訊的陣列。
一般來說，在進行地址查詢時，只會傳回 "results" 陣列中的一個項目，但是如果地址查詢不明確，地理編碼器可能會傳回數個結果。
XML
<GeocodeResponse>
<status>OK</status>
<result>
<type>street_address</type>
<formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address>
<address_component>
<long_name>1600</long_name>
<short_name>1600</short_name>
<type>street_number</type>
</address_component>
<address_component>
<long_name>Amphitheatre Parkway</long_name>
<short_name>Amphitheatre Pkwy</short_name>
<type>route</type>
</address_component>
<address_component>
<long_name>Mountain View</long_name>
<short_name>Mountain View</short_name>
<type>locality</type>
<type>political</type>
</address_component>
<address_component>
<long_name>Santa Clara County</long_name>
<short_name>Santa Clara County</short_name>
<type>administrative_area_level_2</type>
<type>political</type>
</address_component>
<address_component>
<long_name>California</long_name>
<short_name>CA</short_name>
<type>administrative_area_level_1</type>
<type>political</type>
</address_component>
<address_component>
<long_name>United States</long_name>
<short_name>US</short_name>
<type>country</type>
<type>political</type>
</address_component>
<address_component>
<long_name>94043</long_name>
<short_name>94043</short_name>
<type>postal_code</type>
</address_component>
<geometry>
<location>
<lat>37.4224428</lat>
<lng>-122.0842467</lng>
</location>
<location_type>ROOFTOP</location_type>
<viewport>
<southwest>
<lat>37.4212648</lat>
<lng>-122.0856069</lng>
</southwest>
<northeast>
<lat>37.4239628</lat>
<lng>-122.0829089</lng>
</northeast>
</viewport>
</geometry>
<place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id>
<plus_code>
<global_code>849VCWC8+X8</global_code>
<compound_code>CWC8+X8 Mountain View, CA</compound_code>
</plus_code>
</result>
</GeocodeResponse>
請注意，XML 回應是由單一 <GeocodeResponse> 和兩個頂層元素組成：
<status>包含要求的中繼資料。請參閱下方的狀態碼。- 零或多個
<result>元素，每個元素都包含一組經過地理編碼的地址資訊和幾何圖形資訊。
XML 回應要比 JSON 回應長得多。因此，我們建議您將 json 做為偏好的輸出旗標，除非您的服務因故需要 xml。此外，處理 XML 樹狀結構時需要特別注意，以參照適當的節點和元素。如需輸出輸出的建議設計模式，請參閱
使用 XPath 剖析 XML。
- XML 結果會納入根
<GeocodeResponse>元素中。 - JSON 會使用多個陣列 (
types) 來表示含有多個元素的項目，而 XML 則是使用多個單數元素 (<type>)。 - 空白元素在 JSON 中以空白陣列表示，但 XML 中則不會顯示任何這類元素。而不會產生結果的回應會傳回 JSON 中空白的
results陣列，但 XML 中不會傳回<result>元素。
狀態碼
地理編碼回應物件中的 "status" 欄位含有要求的狀態，且可能包含偵錯資訊，可協助您追蹤地理編碼無法正常運作的原因。"status" 欄位可能包含下列的值：
"OK"表示沒有發生任何錯誤。地址剖析成功，且系統傳回至少一組地理編碼。"ZERO_RESULTS"表示地理編碼成功，但沒有傳回任何結果。如果地理編碼器收到不存在的address，就有可能發生這種情況。OVER_DAILY_LIMIT表示下列任一項目：- API 金鑰遺失或無效。
- 您的帳戶尚未啟用帳單功能。
- 超過自行設定的用量上限。
- 您提供的付款方式已失效 (例如信用卡已過期)。
請參閱地圖常見問題瞭解如何解決這個問題。
"OVER_QUERY_LIMIT"表示您已超過配額。"REQUEST_DENIED"表示您的要求遭到拒絕。"INVALID_REQUEST"通常表示缺少查詢內容 (address、components或latlng)。"UNKNOWN_ERROR"表示伺服器發生錯誤，因此無法處理要求。如果再試一次，要求可能會成功。
錯誤訊息
當地理編碼器傳回 OK 以外的狀態碼時，Geocoding 回應物件中可能會多出一個 error_message 欄位。這個欄位包含更詳細的狀態碼原因。
結果
當地理編碼器傳回結果時，會將結果置於 (JSON) results 陣列中。即使地理編碼器沒有傳回任何結果 (例如位址不存在時)，它還是會傳回一個空白的 results 陣列。(XML 回應由零或多個 <result> 元素組成)。
一般結果包含下列欄位：
types[]陣列表示傳回結果的「類型」。這個陣列包含一組零或多個標記，用於識別結果中傳回的特徵類型。舉例來說，「Chicago」的地理編碼會傳回「locality」，表示「Chicago」代表城市，同時傳回「political」，表示其為政治實體。如果地址元件沒有已知的類型，元件可能擁有空白類型陣列。API 可能會視需要新增類型值。詳情請參閱地址類型和地址元件。formatted_address是包含這個位置使用者可理解地址的字串。這個地址通常等於郵寄地址。請注意，由於授權上的限制，部分國家/地區 (例如英國) 不允許散布真實的郵寄地址。
理論上，格式化地址是由一或多個「地址元件」組成。舉例來說，「111 8th Avenue, New York, NY」這個地址包含以下元件：「111」(門牌號碼)、「8th Avenue」(路名)、「New York」(城市) 和「NY」(美國州名)。
請勿以程式輔助方式剖析格式化地址。建議您改用個別地址元件，API 回應除了包含格式化地址欄位之外，也會包含這些元件。
address_components[]是一個陣列，其中包含適用於此地址的個別元件。每個地址元件通常會包含下列欄位：
types[]是一個陣列，用來指出地址元件的「類型」。請參閱支援類型清單。long_name是地理編碼器所傳回地址元件的完整文字說明或名稱。short_name是地址元件的縮寫文字名稱 (如有)。舉例來說，阿拉斯加州地址元件的long_name可能為「Alaska」，而short_name則為 2 個字母的郵政簡碼「AK」。
address_components[]陣列的注意事項如下：- 地址元件陣列包含的元件可能比
formatted_address更多。 - 除了
formatted_address中所含的政治實體以外，這個陣列不一定會納入內含地址的所有政治實體。如要擷取包含特定地址的所有政治實體，建議您使用反向地理編碼，將地址的經緯度做為參數傳遞至要求。 - 兩次要求之間的回應格式不一定相同。特別是，
address_components的數量會因要求的地址而異，對於同一個地址，數量也可能會隨時間改變。元件在陣列中的位置可能會變更。元件類型也可能會變更。後續回應中可能會缺少特定元件。
如要處理元件陣列，您應剖析回應，並透過運算式選取適當的值。請參閱 剖析回應指南。
postcode_localities[]是一個陣列，表示郵遞區號中包含的所有地區。只有當結果是包含多個區域的郵遞區號時，系統才會顯示這個選項。geometry包含下列資訊：location包含經過地理編碼的經緯度值。如果是一般的地址查詢，這個欄位通常是最重要的。location_type會儲存指定位置的其他相關資料。目前支援下列值："ROOFTOP"表示傳回的結果是精確的地理編碼，因為位置資訊的準確度能精確地呈現為街道地址。"RANGE_INTERPOLATED"表示傳回的結果反映了在兩個精確點 (例如交集) 之間插入的近似值 (通常在道路上)。一般而言，當街道地址行數無法使用屋頂地理編碼時，通常會傳回內插結果。"GEOMETRIC_CENTER"表示傳回的結果是結果的幾何中心，例如折線 (例如街道) 或多邊形 (區域)。"APPROXIMATE"表示傳回的結果是約略值。
viewport包含建議傳回結果的可視區域，指定兩個可定義經緯度可視區域定界框的southwest與northeast角落的緯度值。一般而言，可視區域用於向使用者顯示搜尋結果時，會參考頁框。bounds(選擇性傳回) 會儲存可完全包含傳回結果的定界框。請注意，這些邊界可能會與建議的可視區域不符。(舉例來說，從舊金山開始是舊金山市的法拉倫群島，但該島嶼的可視區域不應傳回)。
-
plus_code(請參閱開放式定位碼和加號代碼) 是經過編碼的位置參照，取自緯度和經度座標，代表區域：1/8000 度 / 1/8000 度 (等於赤道約 14m x 14m) 或更小。Plus Code 可用來取代街道地址，用於在沒有地址 (沒有編號或街道未命名) 的位置。API 不一定會傳回 Plus Codes。當服務確實傳回 Plus Code 時，會將其格式化為全域代碼和複合程式碼：
global_code是 4 個字元的區碼，加上 6 個字元以上的地區代碼 (例如 849VCWC8+R9)。compound_code是 6 個字元以上的本地程式碼，具有明確的位置 (CWC8+R9, Mountain View, CA, USA)。請勿以程式輔助方式剖析這個內容。
-
partial_match指出地理編碼器沒有傳回與原始要求完全相符的結果，但可以比對部分要求的地址。建議您檢查原始要求，確認是否有拼寫錯誤和/或不完整的地址。出現部分相符結果的最常見原因，是系統在要求中傳遞的縣市內找不到街道地址。如果要求比對同一個縣市內的兩個或更多地點，也可能會傳回部分相符的結果。舉例來說，「Hillpar St, Bristol, UK」會傳回 Henry Street 和 Henrietta Street 這兩項部分相符的結果。請注意，如果要求包含拼寫錯誤的地址元件，地理編碼服務可能就會建議使用替代地址。透過這種方式觸發的建議，也會標示為部分相符。
place_id是可用於其他 Google API 的專屬 ID。舉例來說，您可以使用 Places API 要求中的place_id來取得當地商家的詳細資料，例如電話號碼、營業時間、使用者評論等等。請參閱地點 ID 總覽。
地址類型和地址元件類型
結果中的 types[] 陣列表示地址類型。地址類型包括街道地址、國家/地區或政治實體。address_components[] 中也有 types[] 陣列，指出地址中每個部分的類型。例如門牌號碼或國家/地區。(以下列出類型的完整清單)。地址可能有多種類型。這些類型可視為「標記」。
舉例來說，許多城市都會加上 political 和 locality 標記。
地理編碼器可在地址類型和地址元件類型陣列中支援及傳回下列類型：
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表示具名搜尋點。一般來說，這些「搜尋點」是當地著名的實體，無法輕易歸入其他類別，例如「帝國大廈」或「艾菲爾鐵塔」。
如果類型清單為空白，表示特定地址元件沒有已知的類型 (例如法國的 Lieu-dit)。
除了上述屬性以外，地址元件也可能包含本文所列的類型。請注意，這份清單尚未含括完整內容，隨時可能變更。
floor表示建築物地址的樓層。establishment通常表示尚未歸類的地點。landmark表示附近地點，做為導航輔助參考。point_of_interest表示具名搜尋點。parking表示停車場。post_box表示特定郵政信箱。postal_town表示地理區域分組 (例如locality和sublocality)，在部分國家/地區用於郵寄地址。room表示建築物地址的房號。street_number表示精確的門牌號碼。bus_station、train_station和transit_station表示公車、火車或大眾運輸停靠站的位置。
可視區域自訂調整
在「地理編碼」要求中，您可以指示「地理編碼」服務在特定檢視區塊 (以定界框表示) 中，優先顯示特定結果。您只要在要求網址中設定 bounds 參數即可。
bounds 參數定義了這個定界框的西南角和東北角的緯度/經度座標，並以直立線 (|) 字元分隔座標。
舉例來說，「Washington」的地理編碼一般會傳回美國華盛頓州的州：
要求：
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
回應：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
不過，如果您加入 bounds 引數，藉此定義美國東北部周圍的定界框，這類地理編碼就會傳回華盛頓特區的城市：
要求：
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
回應：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
區域自訂調整
在 Geocoding 要求中，您可以使用 region 參數，指示 Geocoding 服務將偏誤傳送至特定區域的結果。這個參數使用 ccTLD (國家/地區代碼頂層網域) 引數來指定地區偏誤。多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些例外情況。舉例來說，英國王國的 ccTLD 為「uk」(.co.uk)，其 ISO 3166-1 代碼為「gb」(技術上適用於「英國和北愛爾蘭的英國王國」)。
所有已正式啟動主要「Google 地圖」應用程式的網域，都可以調整地理編碼的結果。請注意，偏誤只會「偏好」特定網域的結果；如果這個網域外還有其他相關結果，可能會納入這些結果。
舉例來說，因為 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.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
包含 region=es (西班牙) 的「Toledo」地理編碼要求將傳回西班牙的城市。
要求：
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
回應：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "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, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
元件篩選
在 Geocoding 回應中，Geocoding API 會傳回限制特定區域的地址結果。您可以使用 components 篩選器指定限制。篩選器包含以直立線 (|) 分隔的 component:value 組合清單。篩選器值支援與其他校正要求要求相同的拼字校正和部分比對方法。如果地理編碼器發現元件篩選器的部分相符，回應將會包含 partial_match 欄位。
可篩選的 components 包括：
postal_code與postal_code和postal_code_prefix相符。country用於比對國家/地區名稱或雙字母 ISO 3166-1 國家/地區代碼。API 遵循用於定義國家/地區的 ISO 標準，且使用國家/地區對應的 ISO 代碼時，篩選功能會發揮最佳效果。
下列 components 可用於影響結果，但不會強制執行：
route符合路線的完整或簡稱。locality與locality和sublocality類型相符。administrative_area符合所有administrative_area層級。
元件篩選注意事項：
- 請勿在要求中重複使用這些元件篩選器，否則 API 會傳回
Invalid_request：country、postal_code、route - 如果要求含有重複的元件篩選器，API 會將這些篩選器視為 AND，而不是 OR。
- 結果與 Google 地圖一致，因此有時會發生非預期的
ZERO_RESULTS回應。在某些情況下，使用 Place Autocomplete 功能可能會提供更好的結果。詳情請參閱這份常見問題。 - 針對每個地址元件，在
address參數或components篩選器中指定，但不能同時指定兩者。如果在兩個位置指定相同的值，可能會導致ZERO_RESULTS。
使用 components=country:GB 的「高街、哈斯汀」
要求：
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
回應：
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
使用 components=country:ES 傳回「Santa Cruz」地區地方的地理編碼要求，會傳回西班牙加那利群島的聖克魯斯-德特內裡費。
要求：
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|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" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "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"
}
只有在您提供排除的篩選器時，元件篩選才會傳回 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 篩選器直接執行不含地址參數的有效查詢。(為完整地址進行地理編碼時，如果要求包含建築物的名稱和號碼，就必須使用 address 參數)。
要求：
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
回應：
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}