「反向地理編碼」會將地圖上的位置轉譯成清楚易懂的地址。您可以使用地點的經緯度座標來表示地圖位置。
反向地理編碼位置時，回應會包含：
這項 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 物件，其中包含：
代表地點的
resultsGeocodeResult物件陣列。反向地理編碼器會在
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參數不會限制搜尋範圍，只會將搜尋結果限制在指定位置的細微程度。而是做為搜尋後的篩選器。granularityAPI 會擷取指定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參數不會限制搜尋範圍，只會顯示指定地址類型。而是做為搜尋後的篩選器。typesAPI 會擷取指定位置的所有結果，然後捨棄不符合指定地址類型(或多個類型) 的結果。如果同時指定
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)。