要求
Geocoding API 要求的格式如下:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
其中 outputFormat
可以是下列任一值:
json
(建議):表示輸出內容為 JavaScript 物件標記法 (JSON);xml
表示 XML 輸出內容
必須使用 HTTPS。
有些參數為必填,有些則為選填。依照網址標準,參數會以 &
字元分隔。
本頁其餘部分會分別說明地理編碼和反向地理編碼,因為每種要求類型都適用不同的參數。
地理編碼 (經緯度查詢) 參數
地理編碼要求中的必要參數:
key
:應用程式的 API 金鑰。這個金鑰可識別您的應用程式,以便進行配額管理。瞭解如何取得金鑰。您必須在要求中指定
address
或components
,或同時指定這兩者:address
:您要進行地理編碼的街道地址或Plus Code。按照相關國家/地區郵政服務使用的格式來指定地址。請避免使用額外的地址項目,例如商家名稱、住房號碼、套房號碼或樓層號碼。街道地址元素應以空格分隔 (這裡以網址轉義為%20
顯示): 請按照這裡指定的格式設定 Plus Codes (加號在網址中會逸出為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
)。
- 全球代碼是 4 個半形字元的區碼,加上 6 個半形字元以上的地區代碼 (例如 849VCWC8+R9 為
components
:元件篩選器,元素以管道符號 (|
) 分隔。如果提供address
,元件篩選器也會做為選用參數接受。元件篩選器中的每個元素都包含component:value
組合,並完全限制地理編碼器的結果。詳情請參閱下方「元件篩選」一節。
如需其他指引,請參閱常見問題。
地理編碼要求中的選用參數:
bounds
:可視區域的邊界框,您可在此範圍內進一步調整地理編碼結果。這個參數只會影響但不會完全限制地理編碼器提供的結果。(詳情請參閱下方的「可視區域自訂調整」)。language
:傳回結果的語言。- 請參閱支援語言清單。Google 會經常更新支援的語言,因此這份清單可能不完整。
- 如果未提供
language
,地理編碼器會嘗試使用Accept-Language
標頭中指定的偏好語言,或傳送要求的網域的原生語言。 - 地理編碼器會盡力提供使用者和當地人都看得懂的街道地址。為達成這個目標,系統會以當地語言傳回街道地址,並視需要將其轉寫為使用者可讀的文字,以便遵循慣用語言。系統會以偏好語言傳回所有其他地址。地址元件會以相同的語言傳回,該語言會從第一個元件中選取。
- 如果名稱無法以偏好語言顯示,地理編碼器會使用最接近的名稱。
- 偏好語言對 API 選擇傳回的結果集合,以及傳回的順序影響不大。地理編碼器會根據語言解讀縮寫字元,例如街道類型的縮寫字元,或是在某種語言中有效,但在其他語言中無效的同義字。舉例來說,在匈牙利文中,「utca」和「tér」分別是「街道」和「廣場」的同義詞。
region
:區碼,指定為 ccTLD (「頂層網域」) 的兩位字元值。這個參數只會影響但不會完全限制地理編碼器提供的結果。(詳情請參閱下方的「區域自訂調整」)。參數也可能會影響根據適用法律產生的結果。components
:元件篩選器,元素以管道符號 (|
) 分隔。如果要求未包含address
,則元件篩選器為必要。元件篩選器中的每個元素都包含component:value
組合,並完全限制地理編碼器的結果。詳情請參閱下方「元件篩選」一節。extra_computations
:使用這個參數,在回應中指定下列額外功能: 如要為同一個 API 要求啟用多項這類功能,請在每項功能的要求中加入extra_computations
參數,例如:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
回應
地理編碼回應會以網址要求中 output
標記所指定的格式傳回,或預設以 JSON 格式傳回。
在這個範例中,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 回應範例。
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" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "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 回應。因此,除非您的服務基於某些原因需要 xml
,否則建議您使用 json
做為偏好的輸出標記。此外,處理 XML 樹狀結構時必須小心謹慎,才能參照適當的節點和元素。請參閱「
使用 XPath 剖析 XML」,瞭解輸出處理作業的部分建議設計模式。
- XML 結果會包裝在根
<GeocodeResponse>
元素中。 - JSON 會以複數陣列 (
types
) 表示含有多個元素的項目,而 XML 則會使用多個單數元素 (<type>
) 表示這些項目。 - 空白元素在 JSON 中會以空陣列表示,但在 XML 中則不會有任何這類元素。例如,如果回應未產生任何結果,就會以 JSON 格式傳回空白的
results
陣列,但不會以 XML 格式傳回<result>
元素。
狀態碼
Geocoding 回應物件中的 "status"
欄位包含要求的狀態,也可能包含偵錯資訊,方便您追查地理編碼功能無法運作的原因。"status"
欄位可能包含下列值:
"OK"
表示沒有發生任何錯誤。地址剖析成功,且系統傳回至少一組地理編碼。"ZERO_RESULTS"
表示地理編碼成功,但沒有傳回任何結果。如果地理編碼器收到不存在的address
,就有可能發生這種情況。OVER_DAILY_LIMIT
表示下列任一項目:- API 金鑰遺失或無效。
- 您的帳戶尚未啟用結帳功能。
- 超過自行設定的用量上限。
- 您提供的付款方式已失效 (例如信用卡已過期)。
請參閱 Google 地圖常見問題,瞭解如何修正這個問題。
"OVER_QUERY_LIMIT"
表示您已超過配額。"REQUEST_DENIED"
表示您的要求遭拒。"INVALID_REQUEST"
通常表示缺少查詢內容 (address
、components
或latlng
)。"UNKNOWN_ERROR"
表示伺服器發生錯誤,因此無法處理要求。如果再試一次,要求可能會成功。
錯誤訊息
當地理編碼器傳回的狀態碼不是 OK
時,Geocoding 回應物件中可能會有額外的 error_message
欄位。這個欄位會提供更多詳細資訊,說明指定狀態碼的原因。
結果
地理編碼器傳回結果時,會將結果放入 (JSON) results
陣列中。即使地理編碼器未傳回任何結果 (例如地址不存在),仍會傳回空白 results
陣列。(XML 回應包含零或多個 <result>
元素)。
典型的結果包含下列欄位:
types[]
陣列會指出傳回結果的「類型」。這個陣列不含任何標記或包含多個標記的組合,用於識別結果中傳回的地圖項目類型。舉例來說,「芝加哥」的地理編碼會傳回「縣市」,指出「芝加哥」是一個城市,並傳回「政治」,指出這是一個政治實體。如果該地址元件沒有已知類型,元件可能會有空的類型陣列。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[]
陣列表示郵遞區號內含的最多 100 個縣市。只有在結果是包含多個縣市的郵遞區號時才會顯示。geometry
包含下列資訊:location
包含經過地理編碼的經緯度值。對於一般地址查詢,這個欄位通常是最重要的。location_type
會儲存指定位置的其他相關資料,目前支援的值如下:"ROOFTOP"
表示傳回的結果是精確的地理編碼,我們擁有精確到街道地址的精確位置資訊。"RANGE_INTERPOLATED"
表示傳回結果反映了插入在兩個精確點 (例如十字路口) 之間的近似值 (通常是在道路上)。如果街道地址沒有精準的地理編碼,系統通常就會傳回插入的結果。"GEOMETRIC_CENTER"
表示傳回結果是結果的幾何圖形中心,包括折線 (例如街道) 或多邊形 (區域)。"APPROXIMATE"
表示傳回結果是約略位置。
viewport
包含顯示傳回結果的建議可視區域,以兩個經緯度值指定可視區域定界框的southwest
和northeast
角落。一般來說,可視區域會用於在向使用者顯示結果時,將結果框起來。bounds
(選擇性傳回) 會儲存可完全涵蓋傳回結果的邊界框。請注意,這些邊界可能與建議可視區域不符。(舉例來說,舊金山行政區包括法拉隆群島,雖然該群島嚴格來說是舊金山的一部分,但可能不應在可視區域中傳回)。
-
plus_code
(請參閱「Open Location Code」和「Plus Codes」) 是經過編碼的位置參照,衍生自經緯度座標,表示面積不超過 1/8000 度 x 1/8000 度 (在赤道區約 14 公尺 x 14 公尺) 的區域。對於沒有詳細地址的地點,Plus Codes 可用於取代街道地址,例如無編號的建築物或無名街道。API 不一定會傳回 Plus Code。如果服務確實傳回 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
是一組專屬 ID,可與其他 Google API 搭配使用。舉例來說,您可以使用 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"
}
區域自訂調整
在地理編碼要求中,您可以使用 region
參數,指示地理編碼服務只傳回特定區域的結果。這個參數會接受 ccTLD (國家/地區代碼頂層網域) 引數,用來指定區域偏好設定。大多數國家/地區頂層網域代碼與 ISO 3166-1 代碼相同,但有一些例外情況。舉例來說,英國的 ccTLD 是「uk」(.co.uk
),而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。
只要是主要 Google 地圖應用程式正式推出的網域,都可以偏向地理編碼結果。請注意,自訂調整功能只是「優先」採用特定網域的結果,如果網域外有更相關的結果,可能也會一併納入。
舉例來說,地理編碼 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 會將這些篩選器視為「且」,而不是「或」。
- 結果與 Google 地圖一致,但有時會產生意外的
ZERO_RESULTS
回應。在某些情況下,使用 Place Autocomplete 可能會提供更優質的結果。詳情請參閱這篇常見問題。 - 針對每個地址元件,請在
address
參數或components
篩選器中指定,但不能同時在兩者中指定。在兩者中指定相同的值可能會導致ZERO_RESULTS
。
如果使用 components=country:GB
為「High St, Hastings」的地理編碼,系統會傳回位於英格蘭海斯廷斯的結果,而非位於美國哈德遜河畔海斯廷斯的結果。
要求:
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"
}