地理編碼服務

總覽

地理編碼是將地址 (例如「1600 Amphitheatre Parkway, Mountain View, CA」) 轉換為地理座標 (例如，緯度 37.423021 與經度 -122.083739) 的程序，您可以用來放置標記或定位地圖。

反向地理編碼是將地理座標轉換成人類看得懂之地址的程序。反向地理編碼器也可讓您找到指定地點 ID 的地址。

Google Maps API 提供一種地理編碼器類別，可以動態地對使用者輸入內容進行地理編碼和反向地理編碼。第一次載入 API 時，您會被分配到一個基本的地理編碼要求配額。一旦您用完此配額，額外的要求將會有每秒的速率限制。如果您想改為對固定、已知的地址進行地理編碼，請參閱地理編碼 Web 服務文件。

地理編碼要求

存取地理編碼服務是非同步的，因為 Google Maps API 需要呼叫外部伺服器。所以，您需要傳遞「回呼」方法，以在要求完成時執行。這個回呼方法會處理結果。請注意，地理編碼器可能會傳回多個結果。

您必須透過 google.maps.Geocoder 物件存取程式碼內的 Google Maps API 地理編碼服務。Geocoder.geocode() 方法會初始化對地理編碼服務的要求，並向它傳遞包含輸入項目的GeocoderRequest 物件常值，以及要在收到回應時執行的回呼方法。

GeocoderRequest 物件常值包含下列欄位：

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

必要參數：您必須僅提供下列其中一個欄位：

  • address - 想要地理編碼的地址。
  • location - 想要取得人類看得懂之最接近地址的 LatLng (或 LatLngLiteral)。地理編碼器會執行「反向地理編碼」。如需詳細資訊，請參閱反向地理編碼。
  • placeId - 想要取得人類看得懂之最接近地址的地點 ID。地點 ID 是可與其他 Google API 搭配使用的唯一識別碼。例如，您可以使用 Google Maps Roads API 傳回的 placeId 來取得貼齊點的地址。如需有關地點 ID 的詳細資訊，請參閱地點 ID 總覽。如果您傳遞 placeId，地理編碼器將會執行「反向地理編碼」。如需詳細資訊，請參閱反向地理編碼。

選擇性參數：

  • bounds - 其中的 LatLngBounds 將會對地理編碼結果進行顯著的遍向。bounds 參數只會影響 (但不會完全限制) 地理編碼器所產生的結果。(如需詳細資訊，請參閱下方的檢視點偏向)。
  • componentRestrictions - 用來將結果限制在特定地區。(如需詳細資訊，請參閱下方的元件篩選)。
  • region - 地區代碼，指定為 IANA 語言 region 子標籤。在大多數情況下，這些標籤會直接對應至常見的 ccTLD (「頂層網域」) 二字元值。region 參數只會影響 (但不會完全限制) 地理編碼器產生的結果。(如需詳細資訊，請參閱下方的地區代碼偏向)。

地理編碼回應

地理編碼服務需要回呼方法，以在擷取到地理編碼器的結果時執行。這個回呼要依序傳遞兩個參數，以保留 results 和 status 碼 (依此順序)。

地理編碼結果

GeocoderResult 物件代表單一地理編碼結果。地理編碼要求可能會傳回多個結果物件：

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

這些欄位說明如下：

  • types[] 是指出傳回結果之「類型」的陣列。此陣列包含零個或多個標籤，指出結果中傳回的特徵類型。例如「芝加哥」的地理編碼會傳回 "locality"，指出「芝加哥」是城市，也會傳回 "political"，指出它是政治實體。
  • formatted_address 是一個字串，包含人類看得懂的此位置地址。此地址通常等於「郵政地址」，有時會因國家/地區而異。(請注意，由於授權限制，有些國家/地區 (例如英國) 不允許散佈實際的郵政地址)。此地址通常是由一或多個「地址元件」所組成。例如，「111 8th Avenue, New York, NY」包含「111 8th Avenue」(街道地址)、「New York」(城市) 和「NY」(美國州別) 等不同的地址元件。這些地址元件如下所述。(如需有關類型的詳細資訊，請參閱下方的類型。
  • address_components[] 是包含個別地址元件 (如上所述) 的陣列。

  • partial_match 指出地理編碼器傳回的結果未能完全符合原始要求，但符合一部分要求的地址。您可以檢查原始要求是否有拼寫錯誤和/或不完整的地址。

    最常出現部分相符的情況是，當要求中傳遞的地區內沒有該街道地址存在時。當相同地區中有兩個以上的位置符合要求時，也會傳回部分相符。例如，"21 Henr St, Bristol, UK" 會傳回與 Henry Street 和 Henrietta Street 部分相符。請注意，如果要求包括拼寫錯誤的地址元件，地理編碼服務會建議替代地址。以這種方式觸發的建議也會標示為部分相符。

  • place_id 是地點的唯一識別碼，可與其他 Google API 搭配使用。例如，您可以搭配 Google Places API 程式庫使用 place_id，以取得當地商家的詳細資料，例如電話號碼、營業時間、使用者評論等。請參閱地點 ID 總覽。
  • postcode_localities[] 是會指明郵遞區號中包含之所有位置的陣列。這只有在結果是包含多個地區的郵遞區號時才會顯示。

  • geometry 包含下列資訊：

    • location 包含完成地理編碼的「latitude,longitude」值。請注意，我們會將此位置以 LatLng 物件傳回，而不是格式化的字串。
    • location_type 儲存有關指定位置的其他資料。目前支援下列值：

      • google.maps.GeocoderLocationType.ROOFTOP 指出傳回的結果可反映精確的地理編碼。
      • google.maps.GeocoderLocationType.RANGE_INTERPOLATED 指出傳回的結果可反映兩個精準點 (例如路口) 之間以內插計算的近似值 (通常是在路上)。當街道地址沒有可用的 rooftop 地理編碼時，通常會傳回內插計算結果。
      • google.maps.GeocoderLocationType.GEOMETRIC_CENTER 指出傳回的結果是如折線 (例如街道) 或多邊形 (地區) 等結果的幾何中心。
      • google.maps.GeocoderLocationType.APPROXIMATE 指出傳回的結果是近似值。

    • viewport 儲存傳回結果的建議檢視點。
    • bounds (選擇性傳回) 儲存可完全包含傳回結果的 LatLngBounds。請注意，這些邊界可能會和建議的檢視點不符。(例如，舊金山包括法拉隆群島，雖然嚴格來說它的確是該城市的一部分，但並不應該在檢視點中傳回)。

地理編碼器會使用瀏覽器偏好的語言設定，或是於載入 API JavaScript 時使用 language 參數所指定的語言，來傳回地址。(如需詳細資訊，請參閱當地語系化)。

地址元件類型

傳回結果內的 types[] 陣列會指出「地址類型」。address_components[] 陣列內也有可能傳回這些類型，以指出特定地址元件的類型。地理編碼器中的地址可以有多種類型。類型可以視為「標籤」。例如，許多城市會擁有 political 與 locality 類型的標籤。

下列是由 HTTP 地理編碼器所支援並傳回的類型：

  • street_address 指出明確的街道地址。
  • route 指出具名路線 (例如 "US 101")。
  • intersection 指出主要交叉路口 (通常是兩條主要道路的交叉)。
  • political 指出政治實體。一般而言，此類型會指出某行政機關的多邊形區域。
  • country 指出國家/地區政治實體，而且這通常是地理編碼器所傳回的最高順序類型。
  • administrative_area_level_1 指出國家/地區層級下的第一順位行政實體。在美國，這些行政層級是州。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_2 指出國家/地區層級下的第二順位行政實體。在美國，這些行政層級是郡。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_3 指出國家/地區層級下的第三順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_4 指出國家/地區層級下的第四順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • administrative_area_level_5 指出國家/地區層級下的第五順位行政實體。此類型指出次級行政單位。並非所有國家/地區都有這些行政層級。
  • colloquial_area 指出常用的實體替代名稱。
  • locality 指出合併的城市或鄉鎮政治實體。
  • sublocality 指出地區下的第一順位行政實體。有些位置會收到以下其中一個額外類型：sublocality_level_1 到 sublocality_level_5。每個 sublocality 層級都是一個行政實體。較大的數字表示較小的地理區域。
  • neighborhood 指出具名的鄰里社區。
  • premise 指出具名位置，通常是有通用名稱的一棟建築物或建築物集合
  • subpremise 指出具名位置下的第一順位實體，通常是具有通用名稱之建築物集合內的單一建築物。
  • postal_code 指出國家/地區內郵寄地址使用的郵遞區號。
  • natural_feature 指出高知名度的自然特徵。
  • airport 指出機場。
  • park 指出具名公園。

空的類型清單指出特定地址元件沒有已知類型，例如法國的 Lieu-dit。

除了上述之外，地址元件也有可能顯示下列類型：

  • post_box 指出特定郵政信箱。
  • street_number 指出明確的門牌號碼。
  • floor 指出建築物地址的樓層。
  • room 指出建築物地址的房室。

狀態碼

status 碼會傳回下列其中一個值：

  • "OK" 指出未發生任何錯誤，已順利剖析地址並且已至少傳回一個地理編碼。
  • "ZERO_RESULTS" 指出地理編碼成功，但是未傳回任何結果。如果傳遞了不存在的 address 給地理編碼器，就可能發生這種情況。
  • "OVER_QUERY_LIMIT" 指出已超出您的配額。
  • "REQUEST_DENIED" 指出您的要求已被拒絕。
  • "INVALID_REQUEST" 通常指出缺少查詢 (address、components 或 latlng)。
  • "UNKNOWN_ERROR" 指出由於發生伺服器錯誤，而無法處理要求。重新嘗試該要求或許會成功。

在此範例中，我們會對地址進行地理編碼，然後在傳回的緯度與經度值處放置標記。請注意，處理常式會傳遞為匿名的函式常值。

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById("map"), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById("address").value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == google.maps.GeocoderStatus.OK) {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert("Geocode was not successful for the following reason: " + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

檢視範例 (geocoding-simple.html)

反向地理編碼 (地址查詢)

「地理編碼」一詞通常是指將人類看得懂的地址轉譯為地圖上的位置。以相反的方式將地圖上的位置轉譯為人類看得懂之地址的程序，稱為「反向地理編碼」。

Geocoder 能直接支援反向地理編碼。使用方式是在 location 參數中提供以逗號分隔的一組緯度/經度組合，而不是提供文字的 address。或者，也可以提供 placeId 以尋找指定地點 ID 的地址。

依位置進行反向地理編碼

下列範例會對緯度/經度值進行地理編碼，然後將地圖置中於該位置，並顯示一個包含格式化地址的資訊視窗。我們會傳回第二個結果，它沒有像第一個結果那麼明確 (在這個範例中，它是一個鄰里社區的名稱)：

function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.731, lng: -73.997}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  var input = document.getElementById('latlng').value;
  var latlngStr = input.split(',', 2);
  var latlng = {lat: parseFloat(latlngStr[0]), lng: parseFloat(latlngStr[1])};
  geocoder.geocode({'location': latlng}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[1]) {
        map.setZoom(11);
        var marker = new google.maps.Marker({
          position: latlng,
          map: map
        });
        infowindow.setContent(results[1].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

檢視範例 (geocoding-reverse.html)。

請注意，在前一個範例中，我們顯示了第二個結果 (藉由選取 results[1])。反向地理編碼器通常會傳回多個結果。地理編碼「地址」並非只是郵政地址，而是任何藉由地理位置命名某個位置的方式。例如，對芝加哥市內的某點進行地理編碼時，地理編碼後的點可能會被標示為街道地址、城市 (芝加哥)、州 (伊利諾伊州)，或是國家/地區 (美國)。上述對於地理編碼器而言，全都是「地址」。反向地理編碼器會傳回所有這些結果。

反向地理編碼器會比對政治實體 (國家/地區、州/省、城市及鄰近地區)、街道地址及郵遞區號。

由先前的查詢所傳回的完整清單如下所示。

results[0].formatted_address: "275-291 Bedford Ave, Brooklyn, NY 11211, USA",
results[1].formatted_address: "Williamsburg, NY, USA",
results[2].formatted_address: "New York 11211, USA",
results[3].formatted_address: "Kings, New York, USA",
results[4].formatted_address: "Brooklyn, New York, USA",
results[5].formatted_address: "New York, New York, USA",
results[6].formatted_address: "New York, USA",
results[7].formatted_address: "United States"

地址傳回是以從最相符到最不相符的順序回傳。一般而言，較確切的地址就是最重要的結果，在本範例中亦是如此。請注意，我們會從最特定的街道地址到最不特定的政治實體傳回不同的地址類型，例如鄰近地區、城市、郡、州/省等等。如果您想要配對的是較為廣域的地址，可以檢查 results[].types 欄位。

注意：反向地理編碼不是一門精確的科學。地理編碼器會嘗試在特定容許範圍內找到最接近的可定址位置。

依地點 ID 進行反向地理編碼

下列範例接受地點 ID，尋找對應的地址，然後將地圖置中於該位置。範例也會帶出一個資訊視窗，顯示相關地點的格式化地址：

// Initialize the map.
function initMap() {
  var map = new google.maps.Map(document.getElementById('map'), {
    zoom: 8,
    center: {lat: 40.72, lng: -73.96}
  });
  var geocoder = new google.maps.Geocoder;
  var infowindow = new google.maps.InfoWindow;

  document.getElementById('submit').addEventListener('click', function() {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a reverse geocode.
function geocodePlaceId(geocoder, map, infowindow) {
  var placeId = document.getElementById('place-id').value;
  geocoder.geocode({'placeId': placeId}, function(results, status) {
    if (status === google.maps.GeocoderStatus.OK) {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
          map: map,
          position: results[0].geometry.location
        });
        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert('No results found');
      }
    } else {
      window.alert('Geocoder failed due to: ' + status);
    }
  });
}

檢視範例 (geocoding-place-id.html)。

檢視點偏向

您也可以指示地理編碼服務優先使用指定檢視點 (以邊界方塊表示) 內的結果。方法是在 GeocoderRequest 物件常值內設定 bounds 參數，定義此檢視點的邊界。請注意，偏向只會「優先使用」邊界內的結果；這些邊界外如果有更相關的結果存在，也會包括在其中。

例如，針對 "Winnetka" 進行地理編碼，通常會傳回此芝加哥近郊：

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

然而，如果指定 bounds 參數，並對洛杉磯的聖費爾南多谷定義邊界方塊，將會使此地理編碼在該位置傳回稱為「Winnetka」的鄰里社區：

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "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"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

地區代碼偏向

您也可以設定地理編碼服務，以使用 region 參數明確傳回偏向特定地區的結果。此參數使用指定為 IANA 語言 region 子標籤的地區代碼。在大多數情況下，這些標籤會直接對應至常見的 ccTLD (「頂層網域」) 二字元值，例如「co.uk」中的「uk」。在某些情況下，region 標籤也支援 ISO-3166-1 代碼，有時候會與 ccTLD 值不同 (例如「Great Britain」的「GB」)。

每個主要的 Google 地圖應用程式提供地理編碼的網域，都可傳送地理編碼要求。請注意，偏向只會「優先使用」特定地區內的結果；此地區外如果有更相關的結果存在，也會包括在其中。

例如，由於地理編碼服務的預設網域設定為美國，因此「Toledo」的地理編碼會傳回此結果：

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

如果將 region 欄位設定為 'es' (西班牙)，「Toledo」的地理編碼結果則會傳回這座位於西班牙的城市：

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "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":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

元件篩選

您也可以設定地理編碼服務，以傳回限制在特定地區的地址結果。如果要指定限制，請使用 componentRestrictions 參數。篩選器包含下列的一或多個項目：route、locality、administrativeArea、postalCode 或 country。只有符合所有篩選器的結果才會傳回。篩選器值和其他地理編碼要求一樣，支援相同的拼字校正與部分相符方法。

下列範例函式示範使用 componentRestrictions 參數，依 country 和 postalCode 來進行篩選：

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

傳送您對下列選項的寶貴意見...

這個網頁
文件意見
Google Maps Javascript API
Google Maps Javascript API
產品意見
需要協助嗎？請前往我們的支援網頁。