Place Autocomplete Data API ช่วยให้คุณสามารถดึงข้อมูลการคาดคะเนสถานที่โดยใช้โปรแกรม เพื่อสร้างประสบการณ์การเติมข้อความอัตโนมัติที่กำหนดเองโดยมีระดับการควบคุมที่ละเอียดยิ่งขึ้นเมื่อเทียบกับวิดเจ็ตการเติมข้อความอัตโนมัติ ในคู่มือนี้ คุณจะได้เรียนรู้วิธีใช้ Place Autocomplete Data API เพื่อสร้างคำขอเติมข้อความอัตโนมัติตามคำค้นหาของผู้ใช้
ตัวอย่างต่อไปนี้จะแสดงการผสานรวมแบบล่วงหน้าอย่างง่าย ป้อนคำค้นหา แล้วคลิก เพื่อเลือกผลการค้นหาที่ต้องการ
คำขอเติมข้อความอัตโนมัติ
คำขอเติมข้อความอัตโนมัติจะใช้สตริงอินพุตคำค้นหาและแสดงผลรายการการคาดคะเนสถานที่ หากต้องการส่งคําขอเติมข้อความอัตโนมัติ โปรดโทรหา 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;
จำกัดการคาดคะเนการเติมข้อความอัตโนมัติ
โดยค่าเริ่มต้น ฟีเจอร์เติมข้อความอัตโนมัติจะแสดงสถานที่ทุกประเภท โดยลำเอียงสำหรับการคาดคะเนใกล้กับตำแหน่งของผู้ใช้ และดึงช่องข้อมูลทั้งหมดที่มีอยู่สำหรับสถานที่ที่เลือกของผู้ใช้ ตั้งค่าตัวเลือกการเติมข้อความอัตโนมัติเพื่อแสดงการคาดคะเนที่เกี่ยวข้องมากขึ้น โดยการจำกัดหรือให้น้ำหนักผลลัพธ์
การจำกัดผลการค้นหาจะทำให้วิดเจ็ตการเติมข้อความอัตโนมัติไม่สนใจผลการค้นหาที่อยู่นอกพื้นที่การจำกัด แนวทางทั่วไปคือการจำกัดผลลัพธ์ให้อยู่ภายในขอบเขตของแผนที่ ผลลัพธ์การให้น้ำหนักจะทำให้วิดเจ็ตการเติมข้อความอัตโนมัติแสดงผลลัพธ์ภายในพื้นที่ที่ระบุ แต่รายการที่ตรงกันบางรายการอาจอยู่นอกพื้นที่ดังกล่าว
ใช้พร็อพเพอร์ตี้ origin
เพื่อระบุจุดเริ่มต้นที่จะคำนวณระยะทางทางภูมิศาสตร์ไปยังปลายทาง ถ้าละเว้นค่านี้ ระยะทางจะไม่แสดงผล
ใช้พร็อพเพอร์ตี้ includedPrimaryTypes
เพื่อระบุประเภทสถานที่สูงสุด 5 ประเภท
หากไม่ได้ระบุประเภท ระบบจะแสดงผลสถานที่ทุกประเภท
ดูรายละเอียดสถานที่
หากต้องการแสดงผลออบเจ็กต์ Place
จากผลการคาดการณ์สถานที่ ก่อนอื่นให้เรียก toPlace()
แล้วเรียก fetchFields()
ในออบเจ็กต์ Place
ที่ได้ (ระบบจะรวมรหัสเซสชันจากการคาดการณ์สถานที่ไว้แล้วโดยอัตโนมัติ) การโทร 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;
โทเค็นของเซสชัน
โทเค็นเซสชันจะจัดกลุ่มการค้นหาและขั้นตอนการเลือกของการค้นหาที่เติมข้อความอัตโนมัติของผู้ใช้ไว้เป็นเซสชันที่แยกกันเพื่อวัตถุประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์ เซสชันนี้จะสรุปเมื่อผู้ใช้เลือกสถานที่และทำการโทรติดต่อรายละเอียดสถานที่
หากต้องการสร้างโทเค็นเซสชันใหม่และเพิ่มลงในคำขอ ให้สร้างอินสแตนซ์ของ
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
คำแนะนำโทเค็นเซสชัน
- ใช้โทเค็นเซสชันสำหรับการเรียกที่เติมข้อความอัตโนมัติทุกครั้ง
- สร้างโทเค็นใหม่สำหรับแต่ละเซสชัน
- ส่งโทเค็นเซสชันที่ไม่ซ้ำกันสําหรับเซสชันใหม่แต่ละเซสชัน การใช้โทเค็นเดียวกันสำหรับมากกว่า 1 เซสชันจะทำให้ระบบเรียกเก็บเงินคำขอแต่ละรายการแยกกัน
คุณสามารถเลือกที่จะยกเว้นโทเค็นเซสชันของการเติมข้อความอัตโนมัติจากคำขอได้ หากไม่ระบุโทเค็นเซสชัน ระบบจะเรียกเก็บเงินคำขอแต่ละรายการแยกกัน ซึ่งจะทริกเกอร์ SKU รุ่นเติมข้อความอัตโนมัติ - ต่อคำขอ หากคุณนำโทเค็นเซสชันมาใช้ซ้ำ ระบบจะถือว่าเซสชันไม่ถูกต้องและจะเรียกเก็บเงินจากคำขอนั้นเสมือนว่าไม่ได้ให้โทเค็นเซสชันไว้
ตัวอย่าง
ขณะที่ผู้ใช้พิมพ์ข้อความค้นหา ระบบจะเรียกคำขอเติมข้อความอัตโนมัติทุก 2-3 การกดแป้นพิมพ์ (ไม่ใช่ต่ออักขระ) และแสดงรายการผลลัพธ์ที่เป็นไปได้ เมื่อผู้ใช้เลือกจากรายการผลลัพธ์ ระบบจะนับการเลือกเป็นคำขอ และคำขอทั้งหมดที่เกิดขึ้นในระหว่างการค้นหาจะถูกรวมกลุ่มและนับเป็นคำขอเดียว หากผู้ใช้เลือกสถานที่ คำค้นหาจะใช้โดยไม่มีค่าใช้จ่าย และจะมีการเรียกเก็บเงินเฉพาะคำขอข้อมูลสถานที่เท่านั้น หากผู้ใช้ไม่เลือกตัวเลือกภายใน 2-3 นาทีนับจากเริ่มต้นเซสชัน ระบบจะเรียกเก็บเงินเฉพาะคำค้นหาเท่านั้น
จากมุมมองของแอป การดำเนินเหตุการณ์จะมีลักษณะดังนี้
- ผู้ใช้เริ่มพิมพ์ข้อความค้นหาเพื่อค้นหา "ปารีส ฝรั่งเศส"
- เมื่อตรวจพบอินพุตของผู้ใช้ แอปจะสร้างโทเค็นเซสชันใหม่ชื่อ "โทเค็น A"
- ขณะที่ผู้ใช้พิมพ์ API จะส่งคำขอเติมข้อความอัตโนมัติทุกๆ 2-3 อักขระ โดยแสดงรายการผลลัพธ์ที่เป็นไปได้ใหม่สำหรับแต่ละรายการ
"P"
"พาร์"
"ปารีส"
"ปารีส, Fr"
- เมื่อผู้ใช้เลือก ให้ทำดังนี้
- ระบบจะจัดกลุ่มคําขอทั้งหมดที่เกิดจากคําค้นหาและเพิ่มลงในเซสชันซึ่งแสดงด้วย "โทเค็น A" เป็นคําขอเดียว
- การเลือกของผู้ใช้จะนับเป็นคำขอรายละเอียดสถานที่ และเพิ่มลงในเซสชันซึ่งแสดงด้วย "โทเค็น A"
- เซสชันสิ้นสุดลง และแอปทิ้ง "โทเค็น A"
ใส่โค้ดตัวอย่างให้ครบถ้วน
ส่วนนี้ประกอบด้วยตัวอย่างทั้งหมดที่แสดงวิธีใช้ Place Autocomplete Data APIวางการคาดคะเนการเติมข้อความอัตโนมัติ
ตัวอย่างต่อไปนี้แสดงการเรียกใช้ fetchAutocompleteSuggestions()
สำหรับอินพุต "Tadi" จากนั้นเรียกใช้ 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> <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()
ตามการค้นหาของผู้ใช้ แสดงรายการสถานที่ที่คาดการณ์ในการตอบกลับ และดึงข้อมูลรายละเอียดสถานที่ของสถานที่ที่เลือกในท้ายที่สุด ตัวอย่างนี้ยังสาธิตการใช้โทเค็นเซสชันเพื่อจัดกลุ่มการค้นหาของผู้ใช้กับคำขอรายละเอียดสถานที่ขั้นสุดท้าย
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> <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>