反向地理編碼位置

歐洲經濟區 (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 第 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 物件，其中包含：

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

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

    1. GeocodeResult.types：這個陣列會指出結果的整體類型。可能的值來自「地點類型 (新版)」頁面的表 A 和表 B。
    2. GeocodeResult.addressComponents[].types：每個地址元件都有 types 陣列，指出地址特定部分的類型。這些值來自「地點類型 (新版)」頁面的「地址類型和地址元件類型」表格。

    反向地理編碼器會在 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 會預設為 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/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"
    },
    ...
  ]
}

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