Place Autocomplete Data API 可讓您透過程式輔助方式擷取地點預測結果,以比自動完成小工具提供更精細的控管能力,進一步打造自訂的自動完成體驗。本指南將說明如何使用 Place Autocomplete Data API,根據使用者查詢提出自動完成要求。
下例顯示簡單的預先輸入整合。輸入搜尋查詢,然後按一下即可選取搜尋結果。
Autocomplete 要求
自動完成要求會接受查詢輸入字串,並傳回地點預測結果清單。如要提出 Autocomplete 要求,請呼叫 fetchAutocompleteSuggestions()
並傳遞包含必要屬性的要求。input
屬性包含要搜尋的字串;在一般應用程式中,這個值會在使用者輸入查詢時更新。要求應包含用於計費的 sessionToken
。
下列程式碼片段示範如何建立要求主體及新增工作階段符記,然後呼叫 fetchAutocompleteSuggestions()
來取得 PlacePrediction
清單。
// Add an initial request body. let request = { input: "Tadi", locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78, }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ["restaurant"], language: "en-US", region: "us", }; // Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. // @ts-ignore request.sessionToken = token;
限制 Autocomplete 預測結果
根據預設,Place Autocomplete 會顯示所有地點類型 (優先顯示使用者所在位置附近的預測結果),並擷取使用者所選地點的所有可用資料欄位。您可以限製或自訂調整結果,將 Place Autocomplete 選項設為顯示更相關的預測結果。
限制結果後,Autocomplete 小工具會略過超出限制區域的所有結果。常見做法是將結果限制在地圖範圍內。自訂調整結果會讓 Autocomplete 小工具顯示指定區域內的結果,但部分相符的結果可能不在該區域。
使用 origin
屬性指定起點,藉此計算與目的地之間的測地距離。如果省略這個值,系統就不會傳回距離。
使用 includedPrimaryTypes
屬性指定最多五個地點類型。如果沒有指定類型,系統就會傳回所有類型的地點。
取得 Place Details
如要從地點預測結果傳回 Place
物件,請先呼叫 toPlace()
,然後對產生的 Place
物件呼叫 fetchFields()
(系統會自動加入地點預測結果的工作階段 ID)。呼叫 fetchFields()
會結束自動完成工作階段。
let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place. await place.fetchFields({ fields: ["displayName", "formattedAddress"], }); const placeInfo = document.getElementById("prediction"); placeInfo.textContent = "First predicted place: " + place.displayName + ": " + place.formattedAddress;
工作階段符記
工作階段符記會將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段,以用於計費。工作階段是從使用者開始輸入時開始。使用者選取地點並呼叫 Place Details 時,工作階段就會結束。
如要建立新的工作階段符記並加到要求中,請建立 AutocompleteSessionToken
的執行個體,然後設定要求的 sessionToken
屬性來使用權杖,如以下程式碼片段所示:
// Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. // @ts-ignore request.sessionToken = token;
系統會在呼叫 fetchFields()
時結束工作階段。建立 Place
執行個體後,系統會自動處理這項作業,因此您不必將工作階段權杖傳遞至 fetchFields()
。
await place.fetchFields({ fields: ["displayName", "formattedAddress"], });
await place.fetchFields({ fields: ['displayName'], });
建立新的 AutocompleteSessionToken
執行個體,為下一個工作階段建立工作階段符記。
工作階段符記建議:
- 所有 Place Autocomplete 呼叫都使用工作階段符記。
- 為每個工作階段產生新的權杖。
- 為每個新的工作階段傳遞不重複的工作階段符記。如果多個工作階段使用同一個符記,則每個要求會分別計費。
您可以選擇在要求中省略自動完成工作階段符記。如果省略工作階段符記,每個要求都會分開計費,觸發 Autocomplete - Per Request SKU。假如您重複使用工作階段符記,系統會將工作階段視為無效,並依照未提供工作階段符記的情況收取相關要求費用。
範例
使用者輸入查詢時,系統會每隔幾個按鍵動作 (而非每個字元) 執行自動完成要求,並傳回可能的結果清單。當使用者從結果清單中做出選擇時,該選項會計為要求,在搜尋期間發出的所有要求都會經過組合並計為單一要求。如果使用者選取地點,則搜尋查詢為免付費,且只收取地點資料要求的費用。如果使用者未在工作階段開始後的幾分鐘內選取,系統只會對搜尋查詢收費。
從應用程式的角度來看,事件流程如下:
- 使用者開始輸入查詢,搜尋「法國巴黎」。
- 偵測到使用者輸入內容時,應用程式會建立新的工作階段符記「符記 A」。
- 在使用者輸入內容時,API 每隔幾個字元就會發出自動完成要求,針對下列各個字元顯示新的可能結果清單:
「P」
「Par」
「Paris」、「
"Paris, Fr」
- 當使用者做出選擇時:
- 從查詢產生的所有要求都會分組並加到由「憑證 A」代表的工作階段,當做單一要求。
- 系統會將使用者的選擇計為地點詳細資料要求,並加進以「權杖 A」代表的工作階段。
- 工作階段結束,應用程式捨棄「Token A」。
完整程式碼範例
本節提供完整範例,說明如何使用 Place Autocomplete Data API。地點自動完成預測
下例示範如何為輸入「Tadi」呼叫 fetchAutocompleteSuggestions()
,然後在第一筆預測結果呼叫 toPlace()
,然後呼叫 fetchFields()
來取得地點詳細資料。
TypeScript
/** * Demonstrates making a single request for Place predictions, then requests Place Details for the first result. */ async function init() { // @ts-ignore const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = await google.maps.importLibrary("places") as google.maps.PlacesLibrary; // Add an initial request body. let request = { input: "Tadi", locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ["restaurant"], language: "en-US", region: "us", }; // Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. // @ts-ignore request.sessionToken = token; // Fetch autocomplete suggestions. const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request); const title = document.getElementById('title') as HTMLElement; title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":')); for (let suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a new list element. const listItem = document.createElement('li'); const resultsElement = document.getElementById("results") as HTMLElement; listItem.appendChild(document.createTextNode(placePrediction.text.toString())); resultsElement.appendChild(listItem); } let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place. await place.fetchFields({ fields: ['displayName', 'formattedAddress'], }); const placeInfo = document.getElementById("prediction") as HTMLElement; placeInfo.textContent = 'First predicted place: ' + place.displayName + ': ' + place.formattedAddress; } init();
JavaScript
/** * Demonstrates making a single request for Place predictions, then requests Place Details for the first result. */ async function init() { // @ts-ignore const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = await google.maps.importLibrary("places"); // Add an initial request body. let request = { input: "Tadi", locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78, }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ["restaurant"], language: "en-US", region: "us", }; // Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. // @ts-ignore request.sessionToken = token; // Fetch autocomplete suggestions. const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request); const title = document.getElementById("title"); title.appendChild( document.createTextNode('Query predictions for "' + request.input + '":'), ); for (let suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a new list element. const listItem = document.createElement("li"); const resultsElement = document.getElementById("results"); listItem.appendChild( document.createTextNode(placePrediction.text.toString()), ); resultsElement.appendChild(listItem); } let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place. await place.fetchFields({ fields: ["displayName", "formattedAddress"], }); const placeInfo = document.getElementById("prediction"); placeInfo.textContent = "First predicted place: " + place.displayName + ": " + place.formattedAddress; } init();
CSS
/* * 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; }
HTML
<html> <head> <title>Place Autocomplete Data API Predictions</title> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <div id="title"></div> <ul id="results"></ul> <p><span id="prediction"></span></p> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- prettier-ignore --> <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))}) ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script> </body> </html>
測試範例
預先輸入工作階段並顯示自動完成功能
這個範例示範如何根據使用者查詢呼叫 fetchAutocompleteSuggestions()
、顯示回應的預測地點清單,最後擷取已選地點的地點詳細資料。本範例也示範如何使用工作階段符記,將使用者查詢與最終 Place Details 要求分組。
TypeScript
let title; let results; let input; let token; // Add an initial request body. let request = { input: "", locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ["restaurant"], language: "en-US", region: "us", }; async function init() { token = new google.maps.places.AutocompleteSessionToken(); title = document.getElementById('title'); results = document.getElementById('results'); input = document.querySelector("input"); input.addEventListener("input", makeAcRequest); request = refreshToken(request) as any; } async function makeAcRequest(input) { // Reset elements and exit if an empty string is received. if (input.target.value == '') { title.innerText = ''; results.replaceChildren(); return; } // Add the latest char sequence to the request. request.input = input.target.value; // Fetch autocomplete suggestions and show them in a list. // @ts-ignore const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request); title.innerText = 'Query predictions for "' + request.input + '"'; // Clear the list first. results.replaceChildren(); for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a link for the place, add an event handler to fetch the place. const a = document.createElement('a'); a.addEventListener('click', () => { onPlaceSelected(placePrediction.toPlace()); }); a.innerText = placePrediction.text.toString(); // Create a new list element. const li = document.createElement('li'); li.appendChild(a); results.appendChild(li); } } // Event handler for clicking on a suggested place. async function onPlaceSelected(place) { await place.fetchFields({ fields: ['displayName', 'formattedAddress'], }); let placeText = document.createTextNode(place.displayName + ': ' + place.formattedAddress); results.replaceChildren(placeText); title.innerText = 'Selected Place:'; input.value = ''; refreshToken(request); } // Helper function to refresh the session token. async function refreshToken(request) { // Create a new session token and add it to the request. token = new google.maps.places.AutocompleteSessionToken(); request.sessionToken = token; return request; } declare global { interface Window { init: () => void; } } window.init = init;
JavaScript
let title; let results; let input; let token; // Add an initial request body. let request = { input: "", locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78, }, origin: { lat: 37.7893, lng: -122.4039 }, includedPrimaryTypes: ["restaurant"], language: "en-US", region: "us", }; async function init() { token = new google.maps.places.AutocompleteSessionToken(); title = document.getElementById("title"); results = document.getElementById("results"); input = document.querySelector("input"); input.addEventListener("input", makeAcRequest); request = refreshToken(request); } async function makeAcRequest(input) { // Reset elements and exit if an empty string is received. if (input.target.value == "") { title.innerText = ""; results.replaceChildren(); return; } // Add the latest char sequence to the request. request.input = input.target.value; // Fetch autocomplete suggestions and show them in a list. // @ts-ignore const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions( request, ); title.innerText = 'Query predictions for "' + request.input + '"'; // Clear the list first. results.replaceChildren(); for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a link for the place, add an event handler to fetch the place. const a = document.createElement("a"); a.addEventListener("click", () => { onPlaceSelected(placePrediction.toPlace()); }); a.innerText = placePrediction.text.toString(); // Create a new list element. const li = document.createElement("li"); li.appendChild(a); results.appendChild(li); } } // Event handler for clicking on a suggested place. async function onPlaceSelected(place) { await place.fetchFields({ fields: ["displayName", "formattedAddress"], }); let placeText = document.createTextNode( place.displayName + ": " + place.formattedAddress, ); results.replaceChildren(placeText); title.innerText = "Selected Place:"; input.value = ""; refreshToken(request); } // Helper function to refresh the session token. async function refreshToken(request) { // Create a new session token and add it to the request. token = new google.maps.places.AutocompleteSessionToken(); request.sessionToken = token; return request; } window.init = init;
CSS
/* * 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; } a { cursor: pointer; text-decoration: underline; color: blue; } input { width: 300px; }
HTML
<html> <head> <title>Place Autocomplete Data API Session</title> <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <input id="input" type="text" placeholder="Search for a place..." /> <div id="title"></div> <ul id="results"></ul> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- The `defer` attribute causes the script to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=init&libraries=places&v=weekly" defer ></script> </body> </html>