您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps JavaScript API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps JavaScript API 與相關服務
  3. 建立適當的金鑰
繼續

自動完成地址和搜尋字詞

簡介

自動完成是 Google Maps JavaScript API 中「地方資訊」程式庫的功能。您可以使用自動完成功能,讓您的應用程式具備 Google 地圖搜尋欄位的「預鍵入搜尋」行為。使用者開始輸入地址的時候,自動完成會填入其餘的部分。

開始使用

在使用 Google Maps JavaScript API 中的「地方資訊」程式庫之前,請先確定已在 Google API Console (您針對 Google Maps JavaScript API 設定的相同專案中)中啟用 Google Places API Web Service。

檢視已啟用的 API 清單:

  1. 前往 Google API Console
  2. 按一下 [Select a project] 按鈕,選取您針對 Google Maps JavaScript API 設定的相同專案,然後按一下 [Open]
  3. 對於 [Dashboard] 上的 API 清單,請搜尋 Google Places API Web Service
  4. 如果您在該清單中看到 API,表示您已設定好。如果列出該 API,請將它啟用:
    1. 在頁面頂端,選取 [ENABLE API] 以顯示 [Library] 標籤。或者,從左側選單,選取 [Library]
    2. 搜尋 Google Places API Web Service,然後從結果清單中選取它。
    3. 選取 [ENABLE]。當此程序完成時,Google Places API Web Service 會出現在 [Dashboard] 上的 API 清單中。

載入程式庫

「地方資訊」服務是一個獨立的程式庫,不在主 Maps JavaScript API 程式碼中。如果要使用此程式庫中所包含的功能,您必須先在 Maps API 啟動程序 URL 中使用 libraries 參數載入它:

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

如需詳細資訊,請參閱程式庫總覽

使用限制與政策

配額

Google Places API Web Service 與「地點自動完成」共用使用配額,如在 Google Places API Web Service 的使用限制文件中所述。使用 Places Library in the Google Maps JavaScript API 時亦適用這些使用限制。每日使用量是以用戶端與伺服器端要求的加總來計算的。

政策

使用 Places Library in the Google Maps JavaScript API 時必須符合針對 Google Places API Web Service 描述的政策

類別摘要

API 提供兩種類型的自動完成小工具,您可以分別透過 AutocompleteSearchBox 類別新增這兩種類型的小工具。此外,您還可以使用 AutocompleteService 類別,以程式設計的方式擷取自動完成結果。

下面是可用類別的摘要:

  • Autocomplete 會將文字輸入欄位新增到您的網頁,並監視該欄位的字元輸入。在使用者輸入文字的時候,自動完成會使用下拉式挑選清單的方式傳回地點預測。使用者從清單中選擇一個地點時,這個地點的相關資訊會傳回到自動完成物件,讓您的應用程式也可以擷取它。請參閱下方的詳細內容。
  • SearchBox 會新增文字輸入欄位到您的網頁,與 Autocomplete 的方式相當類似。差異點如下所述:
    • 主要的差異在於挑選清單中出現的結果。SearchBox 會提供擴充的預測清單,其中包括地點(如 Google Places API 所定義)加上建議的搜尋字詞。例如,如果使用者輸入「pizza in new」,挑選清單可能會包含「pizza in New York, NY」的片語,加上各種披薩店的店名。
    • 基於對搜尋的限制,SearchBox 提供的選項比 Autocomplete 少。使用前者時,您可以將搜尋偏向指定的 LatLngBounds。使用後者則可將搜尋限制在特定國家/地區和特定地點類型,也可以設定邊界。
    請參閱下方的詳細內容。
  • 您可以建立 AutocompleteService 物件,透過程式設計的方式來擷取預測。呼叫 getPlacePredictions() 來擷取相符的地點,或呼叫 getQueryPredictions() 擷取相符的地點加上建議的搜尋字詞。注意:AutocompleteService 不會新增任何 UI 控制項。上述的方法只會傳回一個陣列的預測物件。每個預測物件皆包含預測的文字,也包含參考資訊,以及結果如何符合使用者輸入的詳細資訊。請參閱下方的詳細內容。

本頁面的其他內容提供了範例使用案例,以及如何使用上述類別的詳細資料。

如何使用自動完成

這個影片展示如何使用 Autocomplete,包括示範用法和程式碼範例。

範例:自動完成地址表單

您的應用程式包含地址表單,像是網路購物的送貨地址、信用卡帳單郵寄地址或計程車叫車接送地址表單嗎?自動完成可協助使用者提供詳細資料。

圖 1 顯示一個自動完成文字欄位,以及使用者輸入搜尋查詢所提供的地點預測挑選清單:

一個自動完成文字欄位,以及使用者輸入搜尋查詢所提供的地點預測挑選清單。
圖 1:自動完成文字欄位和挑選清單

當使用者從挑選清單選取一個地址時,您的應用程式可以對地址表單進行填入:

完成的地址表單。
圖 2:完成的地址表單

檢視操作中的地址表單: 檢視範例 (places-autocomplete-addressform.html)

詳閱如何將自動完成新增到您的網頁。

範例:自動完成地圖控制項

自動完成適合用於提示使用者地圖應用程式中的相關資訊,如圖 3 中所示:

顯示部分的城市搜尋查詢和相符地點的自動完成文字欄位。
圖 3:自動完成文字欄位和挑選清單

查看操作過程: 檢視範例 (places-autocomplete-hotelsearch.html)

詳閱如何將自動完成新增到您的網頁。

新增自動完成地點和地址

Autocomplete 可在您的網頁上建立文字輸入欄位、在 UI 選清單中提供地點預測,以及回應 getPlace() 要求傳回地點的詳細資料。挑選清單中每個項目都對應到單一地點(如 Google Places API 的定義)。

Autocomplete 建構函式使用兩個引數:

  • text 類型的 HTML input 元素。這是自動完成服務會監視和附加結果的輸入欄位。
  • options 引數,可包含下列屬性:
    • types 陣列可指定明確類型或類型集合,如下列支援的類型。如果未指定任何類型,則會傳回所有類型。通常只允許單一類型。geocodeestablishment 類型算是例外,您可以放心地混用兩者,但請注意,這與不指定任何類型的效果相同。支援的類型包括:
      • geocode 指示 Places 服務只傳回地理編碼結果,而不傳回店家結果。
      • address 指示 Places 服務只傳回具有精確地址的地理編碼結果。
      • establishment 指示 Places 服務只傳回商家結果。
      • (regions) 類型集合會指示「地方資訊」服務傳回任何與下列類型相符的結果:
        • locality
        • sublocality
        • postal_code
        • country
        • administrative_area1
        • administrative_area2
      • (cities) 類型集合指示 Places 服務傳回與 localityadministrative_area3 相符的結果。
    • boundsgoogle.maps.LatLngBounds 物件,用來指定搜尋地點的區域。結果會偏向於(但不限於)這些邊界內所包含的地方。
    • componentRestrictions 可用於限制結果於特定群組。目前,您可以使用 componentRestrictions 來依國家/地區進行篩選。傳遞國家/地區時,必須使用與 ISO 3166-1 Alpha-2 相容的兩字元國家/地區代碼。
    • placeIdOnly 可用來指示 Autocomplete 小工具只擷取地點 ID。在 Autocomplete 物件上呼叫 getPlace() 時,PlaceResult 只允許設定 place idtypesname 屬性。您可以使用傳回的地點 ID 搭配對地點、地理編碼、路線規劃或距離矩陣服務的呼叫。

設定自動完成的偏向和搜尋區域邊界

您可以使用下列方式對自動完成的結果進行偏向,以選擇特定的大約位置或區域:

  • 於建立 Autocomplete 物件時即設定邊界。
  • 變更現有 Autocomplete 上的邊界。
  • 將邊界設定成地圖的檢視點。
  • 將搜尋限制在特定國家/地區。

詳細資訊請參閱下面各小節內容。

ˊ於建立 Autocomplete 物件時即設定邊界

下面的範例使用 boundstypes 選項來要求類型為「establishment」的店家,並偏好位於指定地理區域內的店家。

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');
var options = {
  bounds: defaultBounds,
  types: ['establishment']
};

autocomplete = new google.maps.places.Autocomplete(input, options);

變更現有 Autocomplete 上的邊界

呼叫 setBounds() 以變更現有 Autocomplete 上的搜尋區域。

// Bias the autocomplete object to the user's geographical location,
// as supplied by the browser's 'navigator.geolocation' object.
function geolocate() {
  if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(function(position) {
      var geolocation = {
        lat: position.coords.latitude,
        lng: position.coords.longitude
      };
      var circle = new google.maps.Circle({
        center: geolocation,
        radius: position.coords.accuracy
      });
      autocomplete.setBounds(circle.getBounds());
    });
  }
}

檢視範例 (places-autocomplete-addressform.html)

將邊界設定成地圖的檢視點

使用 bindTo() 讓結果偏向地圖的檢視點,即使檢視點變更也是一樣。

autocomplete.bindTo('bounds', map);

檢視範例 (places-autocomplete.html)

將搜尋限制在特定國家/地區

使用 componentRestrictions 選項,將自動完成搜尋限制在特定的國家/地區。下列程式碼將結果限制在法國。

var input = document.getElementById('searchTextField');
var options = {
  types: ['(cities)'],
  componentRestrictions: {country: 'fr'}
};

autocomplete = new google.maps.places.Autocomplete(input, options);

下列範例可讓使用者選擇國家,然後將自動完成結果限制在該國家/地區。

// Set the country restriction based on user input.
// Also center and zoom the map on the given country.
function setAutocompleteCountry() {
  var country = document.getElementById('country').value;
  if (country == 'all') {
    autocomplete.setComponentRestrictions([]);
    map.setCenter({lat: 15, lng: 0});
    map.setZoom(2);
  } else {
    autocomplete.setComponentRestrictions({'country': country});
    map.setCenter(countries[country].center);
    map.setZoom(countries[country].zoom);
  }
  clearResults();
  clearMarkers();
}

檢視範例 (places-autocomplete-hotelsearch.html)

自訂自動完成的預留位置文字

根據預設,由自動完成服務建立的文字欄位包含標準的預留位置文字。如果要修改文字,請在 input 元素上設定 placeholder 屬性:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

注意:預設預留位置文字會自動當地語系化。如果您自行指定預留位置的值,則必須處理該值在應用程式內的當地語系化。如需 Google Maps JavaScript API 如何選擇使用語言的詳細資訊,請閱讀當地語系化的文件。

從自動完成取得地點資訊

當使用者從附加到自動文字欄位的預測選取一個地點時,服務會引發 place_changed 事件。您可以在 Autocomplete 物件上呼叫 getPlace() 來擷取 PlaceResult 物件。

自動完成預設會以單行文字顯示完整地址。對於地址表單,取得結構化格式的地址是實用的做法。您可以使用 Autocomplete.getPlace() 來擷取每個自動完成預測的完整詳細資料,包括結構化格式的地址。

如果使用 placeIdOnly 選項,Autocomplete 物件將不會取得地點的詳細資料,因為 PlaceResult 物件只設定 place_idtypesname 屬性。

如果要取得地點詳細資料,請在取得 place_changed 事件時在 Autocomplete 物件上呼叫 getPlace(),以擷取 PlaceResult 物件。接著,您可以使用地理編碼取得位置座標,或使用「地方資訊 」服務取得所選地點的更多資訊。

如需 PlaceResult 物件的詳細資訊,請參閱地點詳細資料結果的文件。

下列範例使用自動完成來填寫地址表單中的欄位。

function fillInAddress() {
  // Get the place details from the autocomplete object.
  var place = autocomplete.getPlace();

  for (var component in componentForm) {
    document.getElementById(component).value = '';
    document.getElementById(component).disabled = false;
  }

  // Get each component of the address from the place details
  // and fill the corresponding field on the form.
  for (var i = 0; i < place.address_components.length; i++) {
    var addressType = place.address_components[i].types[0];
    if (componentForm[addressType]) {
      var val = place.address_components[i][componentForm[addressType]];
      document.getElementById(addressType).value = val;
    }
  }
}

檢視範例 (places-autocomplete-addressform.html)

SearchBox 可讓使用者以文字進行地理搜尋,例如「pizza in New York」或「shoe stores near robson street」。您可以將 SearchBox 附加到文字欄位,在輸入文字的時候,服務會以下拉式挑選清單的方式傳回預測。

SearchBox 會提供擴充的預測清單,其中包括地點(如 Google Places API 所定義)加上建議的搜尋字詞。例如,如果使用者輸入「pizza in new」,挑選清單可能會包含「pizza in New York, NY」的片語,加上各種披薩店的店名。使用者從清單中選擇一個地點時,這個地點的相關資訊會傳回到 SearchBox 物件,您的應用程式也可以擷取它。

SearchBox 建構函式包含兩個引數:

  • text 類型的 HTML input 元素。這是 SearchBox 服務會監視和附加結果的輸入欄位。
  • options 引數可以包含 bounds 屬性:boundsgoogle.maps.LatLngBounds 物件,用來指定搜尋地點的區域。結果會偏向於(但不限於)這些邊界內所包含的地方。

下列程式碼使用 bounds 參數將結果偏向特定地理區域內,透過緯度/經度座標加以指定。

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

變更 SearchBox 的搜尋區域

如果要變更現有 SearchBox 的搜尋區域,請在 SearchBox 物件上呼叫 setBounds() 並傳遞相關的 LatLngBounds 物件。

檢視範例 (places-searchbox.html)

取得 SearchBox 資訊

當使用者從附加到搜尋方塊的預測選取一個項目時,服務會引發 places_changed 事件。您可以在 SearchBox 物件上呼叫 getPlaces() 來擷取包含數個預測的陣列,每個預測都是 PlaceResult 物件。

如需 PlaceResult 物件的詳細資訊,請參閱地點詳細資料結果的文件。

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener('places_changed', function() {
  var places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach(function(marker) {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  var bounds = new google.maps.LatLngBounds();
  places.forEach(function(place) {
    if (!place.geometry) {
      console.log("Returned place contains no geometry");
      return;
    }
    var icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25)
    };

    // Create a marker for each place.
    markers.push(new google.maps.Marker({
      map: map,
      icon: icon,
      title: place.name,
      position: place.geometry.location
    }));

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

檢視範例 (places-searchbox.html)

設定 Autocomplete 和 SearchBox 小工具的樣式

根據預設,AutocompleteSearchBox 提供的 UI 元素已樣式化以包含在 Google 地圖上。您可能要調整樣式以適合您自己的網站。提供下列 CSS 類別。下列所有類別都適用 AutocompleteSearchBox 小工具。

適用於 Autocomplete 和 SearchBox 小工具的 CSS 類別的示意圖
適用於 Autocomplete 和 SearchBox 小工具的 CSS 類別
CSS 類別 描述
pac-container 包含「地點自動完成」服務傳回之預測清單的視覺元素。這份清單會以下拉式清單顯示在 AutocompleteSearchBox 小工具下方。
pac-icon 預測清單中每個項目左邊顯示的圖示。
pac-item AutocompleteSearchBox 小工具提供之預測清單中的項目。
pac-item:hover 使用者將滑鼠指標移至它上方時的項目。
pac-item-selected 使用者透過鍵盤選取它時的項目。注意:選取的項目將會是此類別和 pac-item 類別的成員。
pac-item-query pac-item 內的延伸,這是預測的主要部分。對於地理位置,這個類別會包含地點名稱(如「Sydney」),以及街道名稱和門牌號碼(如「10 King Street」)。對於使用文字的搜尋(如「pizza in New York」),它會包含查詢的完整文字。根據預設,pac-item-query 以黑色顯示。如果 pac-item 有任何其他的文字,這些文字將位於 pac-item-query 的外面,並繼承 pac-item 的樣式。這些文字預設以灰色顯示。額外的文字通常是地址。
pac-matched 這是傳回的預測中符合使用者輸入的部分。這些符合的文字預設以粗體文字醒目提示。請注意,符合的文字可能位於 pac-item 內的任何地方。它不一定是 pac-item-query 的一部分,並可能有部分位於 pac-item-query 內,而其他部分則位於 pac-item 的其餘文字內。

從自動完成服務擷取預測

如果要以程式設計方式擷取預測,請使用 AutocompleteService 類別。AutocompleteService 不會新增任何 UI 控制項。它會傳回一個預測物件陣列,每個預測物件包含預測的文字、參考資訊以及結果如何符合使用者輸入的詳細資料。如果您想要加大對上述 AutocompleteSearchBox 提供的使用者介面的控制,這是實用的做法。

AutocompleteService 會展示下列方法:

  • getPlacePredictions() 傳回地點預測。注意:一個「地點」可能是機構、地理位置或搜尋點,如 Places API 的定義。
  • getQueryPredictions() 會傳回擴充的預測清單,其中包括地點(如 Places API 的定義)加上建議的搜尋字詞。例如,如果使用者輸入「pizza in new」,挑選清單可能會包含「pizza in New York, NY」的片語,加上各種披薩店的店名。

上述兩種方法會以下列格式傳回一個包含五個預測物件的陣列:

  • description 為符合的預測。
  • id 包含代表此地點的唯一識別碼。此識別碼無法用來擷取此地點的相關資訊,但可用來合併此地點的相關資料,以及在個別的搜尋中驗證地點的識別資訊。由於 ID 可能偶爾會變更,因此建議將儲存的地點 ID 與稍後在「詳細資料」要求中針對此相同地點傳回的 ID 做比較,並視需要加以更新。注意:id 已被 place_id 取代,如本頁過時通知中的描述。
  • matched_substrings 於描述中包含一組符合使用者輸入之元素的子字串。這可用於醒目提示您應用程式中的相符子字串。在許多情況下,查詢會顯示為描述欄位的子字串。
    • length 是子字串的長度。
    • offset 是字串偏移,從描述字串的開頭開始計算到符合子字串出現的地方。
  • place_id 是可唯一識別地點的文字型識別碼。如果要擷取地點的相關資訊,請在地點詳細資料要求placeid 欄位中傳遞此識別碼。深入瞭解如何使用地點 ID 參照某個地點
  • reference 包含可用來在未來查詢「詳細資料」服務的語彙基元。此語彙基元可能與對「詳細資料」服務發出的要求中所使用的參照不同。建議定期更新所儲存的地點參照。雖然此權杖可唯一識別此地點,但此地點並不僅限擁有一個權杖:一個地點可能包含許多有效的參照權杖。注意:reference 已被 place_id 取代,如本頁過時通知中的描述。
  • terms 是包含查詢元素的陣列。對於一個地點,每個元素通常是構成地址的一部分。
    • offset 是字串偏移,從描述字串的開頭開始計算到符合子字串出現的地方。
    • value 是相符的字詞。

下列範例會執行一個「pizza near」片語的查詢預測要求,並在清單中顯示結果。

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initService() {
  var displaySuggestions = function(predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK) {
      alert(status);
      return;
    }

    predictions.forEach(function(prediction) {
      var li = document.createElement('li');
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById('results').appendChild(li);
    });
  };

  var service = new google.maps.places.AutocompleteService();
  service.getQueryPredictions({ input: 'pizza near Syd' }, displaySuggestions);
}
<div id="right-panel">
  <p>Query suggestions for 'pizza near Syd':</p>
  <ul id="results"></ul>
</div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=places&callback=initService"
    async defer></script>
// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initService() {
  var displaySuggestions = function(predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK) {
      alert(status);
      return;
    }

    predictions.forEach(function(prediction) {
      var li = document.createElement('li');
      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById('results').appendChild(li);
    });
  };

  var service = new google.maps.places.AutocompleteService();
  service.getQueryPredictions({ input: 'pizza near Syd' }, displaySuggestions);
}

檢視範例 (places-queryprediction.html)

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

這個網頁
Google Maps JavaScript API
Google Maps JavaScript API
需要協助嗎?請前往我們的支援網頁