反向地理編碼位置

歐洲經濟區 (EEA) 開發人員

「反向地理編碼」會將地圖上的位置轉譯成人類可讀的地址。您可以使用地點的經緯度座標表示地圖位置。

反向地理編碼位置時，回應會包含：

這項 API 會傳回各種地址，從最精確的街道地址到較籠統的政治實體，例如社區、城市、郡/縣和州/省。最相符的地址通常是第一個結果。如要比對特定類型的地址，請使用 types 參數。

反向地理編碼要求

反向地理編碼要求是 HTTP GET 要求。您可以將位置指定為非結構化字串：

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

或以查詢參數表示的結構化經緯度座標組合：

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

處理 HTML 表單中擷取的地點元件時，通常會使用結構化格式。

所有其他參數都應以網址參數的形式傳遞，或以 API 金鑰或欄位遮罩等參數的形式，在標頭中做為 GET 要求的一部分傳遞。例如：

傳遞非結構化位置字串

非結構化位置資訊是指以半形逗號分隔的經緯度座標字串格式表示的位置資訊：

https://geocode.googleapis.com/v4/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/v4/geocode/location/37.4225508,-122.0846338"

傳遞結構化位置

使用 location 查詢參數 (類型為 LatLng) 指定結構化位置。LatLng 物件可讓您將經緯度指定為個別查詢參數：

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

使用 OAuth 提出要求

Geocoding API v4 支援 OAuth 2.0 驗證。如要搭配使用 OAuth 和 Geocoding API，必須為 OAuth 權杖指派正確的範圍。Geocoding API 支援下列範圍，可用於反向地理編碼：

  • https://www.googleapis.com/auth/maps-platform.geocode — 適用於所有 Geocoding API 方法。
  • https://www.googleapis.com/auth/maps-platform.geocode.location：僅與 GeocodeLocation 搭配使用，進行反向地理編碼。

此外，您也可以將一般 https://www.googleapis.com/auth/cloud-platform 範圍用於所有 Geocoding API 方法。這個範圍在開發期間很有用，但不適用於正式環境，因為這是允許存取所有方法的通用範圍。

如需更多資訊和範例，請參閱「使用 OAuth」。

反向地理編碼回應

反向地理編碼會傳回 GeocodeLocationResponse 物件，其中包含：

  • 代表地點的 GeocodeResult 物件 results 陣列。

    Geocoding API 回應在 GeocodeResult 的兩個主要位置包含 types 陣列：

    1. GeocodeResult.types：這個陣列會指出結果的整體類型。可能的值來自 Places API 使用的地點類型。詳情請參閱「地點類型表 A 和表 B」。
    2. GeocodeResult.addressComponents[].types：每個地址元件都有一個 types 陣列，用來指出該地址特定部分的類型。這些值取自 Places API 使用的地址類型和地址元件類型表格。

    反向地理編碼器會在 results 陣列中傳回多筆結果。結果不僅是郵寄地址，也可以使用任何表述地理的方式為地點命名。舉例來說，針對芝加哥市的某個定點進行地理編碼時，這個地理編碼定點可以標示為街道地址、城市 (芝加哥)、州名 (伊利諾州) 或國家/地區 (美國)。對地理編碼器而言，這些都是「地址」。反向地理編碼器會將這些類型視為有效結果傳回。

  • plusCode 欄位 (類型為 PlusCode) 包含最接近要求中經緯度的 Plus Code。此外，results 陣列的每個元素都包含 Plus Code。解碼的 Plus Code 與要求點之間的距離小於 10 公尺。

    注意：API 不一定會傳回 Plus Code。

完整的 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 預設會使用該地點的當地語言和文字。如果指定無效的語言代碼，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/v4/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/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    建立回應欄位遮罩，指定要在回應中傳回的欄位。使用網址參數 $fields 或 fields，或使用 HTTP 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至方法。舉例來說，下列要求只會傳回回應的 placeID 欄位。

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    回應如下： 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    詳情請參閱「選擇要傳回的欄位」。