反向地理編碼會將地圖位置轉譯成人類可讀的地址。您可以使用地點的經緯度座標來表示地圖位置。
反向地理編碼位置時，回應會包含：
- 地址的 Place ID
- 地址的 Plus Codes
- 地址詳細資料
這個 API 會傳回各種地址，從最具體的街道地址到較籠統的政治實體，例如社區、城市、郡/縣和州/省。最相符的地址通常是第一個結果。如要比對特定類型的地址，請使用 types 參數。
反向地理編碼要求
反向地理編碼要求是 HTTP GET 要求。您可以將位置指定為非結構化字串：
https://geocode.googleapis.com/v4beta/geocode/location/LATITUDE,LONGITUDE
或以結構化的經緯度座標組合形式，由查詢參數代表：
https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE
您通常會在處理 HTML 表單中擷取的位置元件時，使用結構化格式。
將所有其他參數做為網址參數傳遞，或是將 API 金鑰或欄位遮罩等參數做為 GET 要求的一部分傳遞至標頭。例如：
傳遞非結構化位置字串
非結構化位置是指經緯度座標以半形逗號分隔的字串格式：
https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?key=API_KEY
或是在 curl 指令中：
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ "https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338"
傳遞結構化位置
使用 location 查詢參數 (類型為 LatLng) 指定結構化位置。LatLng 物件可讓您將經緯度指定為個別的查詢參數：
https://geocode.googleapis.com/v4beta/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338 &key=API_KEY
使用 OAuth 提出要求
Geocoding API 4 版支援 OAuth 2.0 驗證機制。如要搭配 Geocoding API 使用 OAuth，必須為 OAuth 權杖指派正確的範圍。Geocoding API 支援下列範圍，可用於反向地理編碼：
https://www.googleapis.com/auth/maps-platform.geocode- 搭配所有 Geocoding API 端點使用。https://www.googleapis.com/auth/maps-platform.geocode.location- 僅用於反向地理編碼的GeocodeLocation。
此外，您也可以為所有 Geocoding API 端點使用一般 https://www.googleapis.com/auth/cloud-platform 範圍。這個範圍在開發期間很實用，但在正式版中則不然，因為這是允許存取所有端點的一般範圍。
如需進一步瞭解相關資訊和範例，請參閱「使用 OAuth」。
反向地理編碼回應
反向地理編碼會傳回 GeocodeLocationResponse 物件，其中包含：
代表地點的
GeocodeResult物件results陣列。反向地理編碼器會在
results陣列中傳回多筆結果。結果不僅是郵寄地址，也可以使用任何表述地理的方式為地點命名。舉例來說，針對芝加哥市的某個定點進行地理編碼時，這個地理編碼定點可以標示為街道地址、城市 (芝加哥)、州名 (伊利諾州) 或國家/地區 (美國)。對地理編碼器而言，這些都是「地址」。反向地理編碼器會將任何一種類型傳回為有效結果。plusCode欄位 (類型為PlusCode) 包含最接近要求中經緯度的 Plus Code。此外，results陣列的每個元素都包含 Plus Code。解碼後的 Plus Code 與要求點之間的距離小於 10 公尺。
完整的 JSON 物件格式如下：
{ "results": [ { "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU", "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU", "location": { "latitude": 37.422588300000008, "longitude": -122.0846489 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.421239319708512, "longitude": -122.0859978802915 }, "high": { "latitude": 37.423937280291511, "longitude": -122.08329991970851 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] } ], "types": [ "street_address" ], "plusCode": { "globalCode": "849VCW83+PM", "compoundCode": "CW83+PM Mountain View, CA, USA" } }, { "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw", "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "location": { "latitude": 37.4220541, "longitude": -122.08532419999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.4207051197085, "longitude": -122.08667318029148 }, "high": { "latitude": 37.423403080291493, "longitude": -122.08397521970851 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "addressComponents": [ { "longText": "1600", "shortText": "1600", "types": [ "street_number" ] }, { "longText": "Amphitheatre Parkway", "shortText": "Amphitheatre Pkwy", "types": [ "route" ], "languageCode": "en" }, { "longText": "Mountain View", "shortText": "Mountain View", "types": [ "locality", "political" ], "languageCode": "en" }, { "longText": "Santa Clara County", "shortText": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ], "languageCode": "en" }, { "longText": "California", "shortText": "CA", "types": [ "administrative_area_level_1", "political" ], "languageCode": "en" }, { "longText": "United States", "shortText": "US", "types": [ "country", "political" ], "languageCode": "en" }, { "longText": "94043", "shortText": "94043", "types": [ "postal_code" ] } ], "types": [ "establishment", "point_of_interest" ], "plusCode": { "globalCode": "849VCWC7+RV", "compoundCode": "CWC7+RV Mountain View, CA, USA" } }, ... ], "plusCode": { "globalCode": "849VCWF8+24H", "compoundCode": "CWF8+24H Mountain View, CA, USA" } }
必要參數
位置
經緯度座標，指定您要取得距離最近且人類可讀的地址。
選用參數
languageCode
傳回結果時使用的語言。
- 請參閱支援語言清單。Google 會經常更新支援的語言，因此這份清單可能不完整。
-
如果未提供
languageCode，API 會預設為en。如果指定無效的語言代碼，API 會傳回INVALID_ARGUMENT錯誤。 - API 會盡力提供使用者和當地人都看得懂的街道地址。為達成這個目標，系統會以當地語言傳回街道地址，並視需要將其轉寫為使用者可讀取的文字，並遵循偏好語言。所有其他地址都會以偏好語言傳回。地址元件會以相同的語言傳回，該語言會從第一個元件中選取。
- 如果名稱無法以偏好語言顯示，API 會使用最接近的名稱。
- 偏好語言對 API 選擇傳回的結果組合，以及傳回的順序影響不大。地理編碼器會根據語言解讀縮寫字元，例如街道類型的縮寫字元，或是在某種語言中有效，但在其他語言中無效的同義字。
regionCode
區碼為 兩個字元的 CLDR 代碼值。沒有預設值。大多數 CLDR 代碼與 ISO 3166-1 代碼相同。
在對地址進行地理編碼時，轉發地理編碼，這個參數可以影響服務傳回的結果，但不會完全限制結果只傳回指定區域。當您要對地點或地點進行地理編碼、反向地理編碼或地點地理編碼時，可以使用這個參數來設定地址格式。無論如何，這個參數都可能會根據適用法律影響搜尋結果。
精細程度
一或多個位置精細度，以
Granularity定義的查詢參數個別指定。如果您指定多個granularity參數，API 會傳回符合任何精細度的所有地址。granularity參數不會將搜尋範圍限制在指定位置精細程度內。granularity則是做為搜尋後的篩選器。API 會擷取指定location的所有結果，然後捨棄不符合指定位置精細度的結果。如果您同時指定
types和granularity，API 只會傳回符合兩者的結果。例如：https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP
&granularity=GEOMETRIC_CENTER &key=API_KEY 類型
一或多個地址類型，以個別查詢參數指定。如果您指定多個
types參數，API 會傳回與任何類型相符的所有地址。types參數不會將搜尋範圍限制為指定的地址類型。types則是做為搜尋後的篩選器。API 會擷取指定位置的所有結果，然後捨棄不符合指定地址類型的結果。如果您同時指定
types和granularity，API 只會傳回符合兩者的結果。例如：https://geocode.googleapis.com/v4beta/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2
&types=locality &key=API_KEY 支援下列值：
地址類型和地址元件類型
回應中
GeocodeResult主體的types陣列表示「地址類型」。地址類型包括街道地址、國家/地區或政治實體。GeocodeResult主體的AddressComponents欄位中的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)。