地理編碼要求和回應

要求

Geocoding API 要求採用下列格式:

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

其中 outputFormat 可以是下列任一值:

  • json (建議使用) 表示輸出格式為 JavaScript 物件註釋 (JSON);或
  • xml 表示輸出內容為 XML

必須提供 HTTPS。

有些是必要參數,有些則是選用參數。依照網址標準,參數會以 & 字元分隔。

本頁其餘部分會分別說明地理編碼和反向地理編碼,因為每種要求可用的參數也不同。

地理編碼 (經緯度查詢) 參數

地理編碼要求的必要參數:

  • address:您要進行地理編碼的街道地址或 plus code。按照相關國家/地區郵政服務所用的格式指定地址。請避免使用其他地址元素,例如商家名稱和單位、套房或樓層號碼。街道地址元素應以空格分隔 (此處如此處所示網址逸出為 %20):
    address=24%20Sussex%20Drive%20Ottawa%20ON
    請按照這裡的說明設定 Plus Codes (加號在網址中會逸出為 %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 組合,並會完整限制地理編碼器顯示的結果。詳情請參閱下方「元件篩選」一節。
  • key:您應用程式的 API 金鑰。為管理配額,此金鑰會識別您的應用程式。瞭解如何取得金鑰

如需其他指引,請參閱常見問題

地理編碼要求中的選用參數:

  • bounds:可視區域的定界框,您可在此範圍內進一步調整地理編碼結果。這個參數只會影響但不會完全限制地理編碼器提供的結果。(詳情請參閱下方的可視區域自訂調整)。
  • language:結果傳回時使用的語言。
    • 查看支援語言清單。Google 會經常更新支援的語言,因此這份清單可能會有遺漏。
    • 如未提供 language,地理編碼器會嘗試使用 Accept-Language 標頭中指定的偏好語言,或傳送要求的網域的原生語言。
    • 地理編碼器會盡可能提供使用者和當地居民都能讀取的街道地址。為達成此目標,系統會以當地語言傳回街道地址,並在必要時音譯為可由使用者讀取的指令碼,並觀察慣用語言。所有其他地址都會以偏好語言傳回。地址元件都是以相同語言傳回,從第一個元件中選出。
    • 如果名稱沒有偏好的語言,地理編碼器會使用最接近的值。
    • 偏好語言對於 API 選擇傳回的結果組合及傳回順序的影響微乎其微。地理編碼器解讀縮寫的方式會因語言而異,例如街道類型的縮寫,或者對其中一種語言可能有效的同義詞。舉例來說,utcaté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 金鑰遺失或無效。
    • 您的帳戶未啟用帳單功能。
    • 已超過自行設定的用量上限。
    • 您提供的付款方式已失效 (例如信用卡已過期)。

    請參閱 Google 地圖常見問題,瞭解如何修正這個問題。

  • "OVER_QUERY_LIMIT" 表示您已超過配額。
  • "REQUEST_DENIED" 表示您的要求遭拒。
  • "INVALID_REQUEST" 通常表示缺少查詢內容 (addresscomponentslatlng)。
  • "UNKNOWN_ERROR" 表示伺服器發生錯誤,因此無法處理要求。如果再試一次,要求可能會成功。

錯誤訊息

如果地理編碼器傳回 OK 以外的狀態碼,地理編碼回應物件中就可能多出 error_message 欄位。這個欄位可提供更多詳細資訊,讓您瞭解特定狀態碼背後的原因。

研究結果

地理編碼器傳回的結果會放置在 (JSON) results 陣列中,即使地理編碼器未傳回任何結果 (例如地址不存在時),還是會傳回空白的 results 陣列,(XML 回應由 0 或多個 <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 包含建議用於顯示傳回結果的可視區域,這兩個值分別代表了可視區域定界框的 southwestnortheast 角。一般來說,當使用者看到可視區域時,會用於為結果建立框架。
    • bounds (選擇性傳回) 會儲存可完全涵蓋傳回結果的定界框。請注意,這些邊界可能與建議可視區域不符。(舉例來說,舊金山行政區包括法拉隆群島,雖然該群島嚴格來說是舊金山的一部分,但可能不會在可視區域中傳回)。
  • plus_code (請參閱「開啟區碼」和「Plus Codes」) 是衍生位置參照,衍生自經緯度座標,代表面積:以度數 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)。請勿以程式輔助方式剖析這個內容。
    在適用情況下,API 會同時傳回全球程式碼和複合程式碼。不過,如果結果是在偏遠位置 (例如海洋或沙漠),系統可能只會傳回全球代碼。
  • partial_match 指出地理編碼器沒有傳回與原始要求完全相符的結果,但可以比對部分要求的地址。建議您檢查原始要求,確認是否有拼寫錯誤和/或不完整的地址。

    出現部分相符結果的最常見原因,是系統在要求中傳遞的縣市內找不到街道地址。如果要求比對同一個縣市內的兩個或更多地點,也可能會傳回部分相符的結果。舉例來說,「Hillpar St, Bristol, UK」會傳回 Henry Street 和 Henrietta Street 這兩項部分相符的結果。請注意,如果要求包含拼寫錯誤的地址元件,地理編碼服務可能就會建議使用替代地址。透過這種方式觸發的建議,也會標示為部分相符。

  • place_id 是一組專屬 ID,可與其他 Google API 搭配使用。舉例來說,您可以在 Places API 要求中使用 place_id 取得當地商家的詳細資料,例如電話號碼、營業時間和使用者評論等等。請參閱地點 ID 總覽

地址類型和地址元件類型

結果中的 types[] 陣列表示「地址類型」。地址類型的例子包括街道地址、國家/地區或政治實體。address_components[] 還提供 types[] 陣列,表示地址中每個部分的類型。例如門牌號碼或國家/地區。(以下為完整的類型清單)。地址可以有多種類型。這些類型可視為「標記」。舉例來說,許多城市都會加上 politicallocality 類型標記。

在地址類型和地址元件類型陣列中,地理編碼器會支援及傳回下列類型:

  • 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_1sublocality_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 表示地理區域分組 (例如 localitysublocality),在部分國家/地區用於郵寄地址。
  • room 表示建築物地址的房號。
  • street_number 表示精確的門牌號碼。
  • bus_stationtrain_stationtransit_station 表示公車、火車或大眾運輸停靠站的位置。

可視區域自訂調整

透過地理編碼要求,您可以指示地理編碼服務優先顯示指定可視區域 (以定界框表示) 內的結果。您可以在要求網址中進行這項操作,方法是設定 bounds 參數。

bounds 參數定義這個定界框的西南角和東北角的經緯度座標,並以直立線 (|) 字元來分隔座標。

舉例來說,「華盛頓」的地理編碼通常會傳回美國華盛頓州的地理編碼:

要求:

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 (國家/地區代碼頂層網域) 引數指定了區域自訂調整。大多數 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&region=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 API 中,Geocoding API 可以傳回僅限特定區域的地址結果。您可以使用 components 篩選器指定限制。篩選器由以直立線 (|) 分隔的 component:value 組合清單組成。篩選器值支援的拼字校正和部分比對方法與其他地理編碼要求相同。如果地理編碼器找到與元件篩選器相符的部分,回應中就會包含 partial_match 欄位。

可篩選的 components 包括:

  • postal_codepostal_codepostal_code_prefix 相符。
  • country 用於比對國家/地區名稱或雙字母 ISO 3166-1 國家/地區代碼。API 遵循 ISO 標準來定義國家/地區,因此使用國家/地區的相應 ISO 代碼時,篩選功能的效果最佳。

下列 components 可能會用來影響結果,但不會強制執行:

  • route 用於比對路線的全名或簡稱。
  • locality 會比對 localitysublocality 類型。
  • administrative_area 與所有 administrative_area 層級相符。

元件篩選相關注意事項:

  • 請勿在要求中重複這些元件篩選器,否則 API 會傳回 Invalid_requestcountrypostal_coderoute
  • 如果要求包含重複的元件篩選器,API 會將這些篩選條件視為「且」,而不是「或」。
  • 結果與 Google 地圖一致,有時可能會產生非預期的 ZERO_RESULTS 回應。在某些情況下,使用 Place Autocomplete 功能可能會提供更符合需求的結果。詳情請參閱這份常見問題
  • 請為每個地址元件指定 address 參數或 components 篩選器,但不能同時指定兩者。如果兩者在兩種情況下指定相同的值,可能會導致 ZERO_RESULTS

加上 components=country:GB 的「High St, Hastings」地理編碼會在英國哈斯丁,而非美國海斯丁-On-Hudson,傳回結果。

要求:

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 de Tenerife。

要求:

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"
}