วาง API ข้อมูลที่เติมข้อความอัตโนมัติ

Place Autocomplete Data API ช่วยให้คุณสามารถดึงข้อมูลการคาดการณ์สถานที่ โดยใช้โปรแกรมเพื่อสร้างประสบการณ์การเติมข้อความอัตโนมัติที่กำหนดเองและสามารถควบคุมได้ละเอียดยิ่งขึ้น มากกว่าที่สามารถทำได้ด้วยวิดเจ็ตการเติมข้อความอัตโนมัติ ในคู่มือนี้ คุณจะได้เรียนรู้วิธีใช้ วาง 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;

index.js

จำกัดการคาดคะเนการเติมข้อความอัตโนมัติ

โดยค่าเริ่มต้น การเติมข้อมูลสถานที่อัตโนมัติจะแสดงสถานที่ทุกประเภท โดยมีความเอนเอียงในการคาดคะเนที่อยู่ใกล้กับผู้ใช้ และดึงข้อมูลฟิลด์ที่มีอยู่ทั้งหมดสำหรับสถานที่ที่เลือกของผู้ใช้ กำหนดสถานที่ ตัวเลือกการเติมข้อความอัตโนมัติเพื่อแสดงการคาดคะเนที่เกี่ยวข้องมากขึ้น โดยการจำกัดหรือให้น้ำหนักผลลัพธ์

การจำกัดผลการค้นหาจะทำให้วิดเจ็ตการเติมข้อความอัตโนมัติละเว้นผลการค้นหาใดๆ พื้นที่จำกัด แนวทางทั่วไปคือการจำกัดผลลัพธ์ให้อยู่ภายในขอบเขตของแผนที่ ผลลัพธ์การให้น้ำหนัก วิดเจ็ตการเติมข้อความอัตโนมัติจะแสดงผลลัพธ์ภายในพื้นที่ที่ระบุ แต่ผลการค้นหาที่ตรงกันทั้งหมดอาจเกิดขึ้น นอกพื้นที่ดังกล่าว

ใช้พร็อพเพอร์ตี้ origin เพื่อระบุจุดต้นทางที่จะคำนวณ ระยะทางตามพื้นโลกไปยังปลายทาง ถ้าละเว้นค่านี้ ระยะทางจะไม่แสดงผล

ใช้includedPrimaryTypes เพื่อระบุประเภทสถานที่ได้สูงสุด 5 ประเภท หากไม่ได้ระบุประเภท ระบบจะแสดงผลสถานที่ทุกประเภท

ดูข้อมูลอ้างอิง API

ดูรายละเอียดสถานที่

หากต้องการส่งคืน 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;
index.js

โทเค็นของเซสชัน

โทเค็นเซสชันจะจัดกลุ่มการค้นหาและขั้นตอนการเลือกของการค้นหาในการเติมข้อความอัตโนมัติของผู้ใช้ให้เป็น เซสชันที่แยกกันเพื่อจุดประสงค์ในการเรียกเก็บเงิน เซสชันจะเริ่มต้นเมื่อผู้ใช้เริ่มพิมพ์ เซสชันนี้จะสรุปเมื่อผู้ใช้เลือกสถานที่และทำการโทรติดต่อรายละเอียดสถานที่

หากต้องการสร้างโทเค็นเซสชันใหม่และเพิ่มลงในคำขอ ให้สร้างอินสแตนซ์ของ AutocompleteSessionToken จากนั้นตั้งค่า sessionToken ของคำขอใช้โทเค็นดังที่แสดงในข้อมูลโค้ดต่อไปนี้ 

// Create a session token.
const token = new AutocompleteSessionToken();

// Add the token to the request.
// @ts-ignore
request.sessionToken = token;

index.js

เซสชันจะสิ้นสุดลงเมื่อ fetchFields() จะถูกเรียก หลังจากสร้างอินสแตนซ์ Place แล้ว คุณไม่จำเป็นต้องผ่านเซสชัน โทเค็นให้กับ fetchFields() เนื่องจากระบบจะจัดการข้อมูลนี้โดยอัตโนมัติ 

await place.fetchFields({
  fields: ["displayName", "formattedAddress"],
});

index.js
 
await place.fetchFields({
    fields: ['displayName'],
  });

สร้างโทเค็นเซสชันสำหรับเซสชันถัดไปโดยสร้างอินสแตนซ์ใหม่ของ AutocompleteSessionToken

คำแนะนำโทเค็นเซสชัน

  • ใช้โทเค็นเซสชันสำหรับการเรียกที่เติมข้อความอัตโนมัติทุกครั้ง
  • สร้างโทเค็นใหม่สำหรับแต่ละเซสชัน
  • ส่งโทเค็นเซสชันที่ไม่ซ้ำกันสําหรับเซสชันใหม่แต่ละเซสชัน การใช้โทเค็นเดียวกันสำหรับมากกว่า 1 เซสชัน จะทำให้แต่ละคำขอถูกเรียกเก็บเงินแยกกัน

คุณเลือกที่จะละเว้นโทเค็นเซสชันที่เติมข้อความอัตโนมัติจากคำขอได้ หากโทเค็นเซสชันคือ แต่ละคำขอจะถูกเรียกเก็บเงินแยกกัน ซึ่งจะทริกเกอร์ฟิลด์ เติมข้อความอัตโนมัติ - ตามคำขอ SKU หากคุณนำโทเค็นเซสชันมาใช้ซ้ำ ระบบจะถือว่าเซสชันนั้นไม่ถูกต้องและจะมีการเรียกเก็บเงินตามคำขอ เสมือนว่าไม่ได้ให้โทเค็นเซสชันไว้

ตัวอย่าง

ขณะที่ผู้ใช้พิมพ์คำค้นหา ระบบจะเรียกคำขอเติมข้อความอัตโนมัติทุกๆ 2-3 การกดแป้นพิมพ์ (ไม่ใช่ต่ออักขระ) และแสดงรายการผลลัพธ์ที่เป็นไปได้ เมื่อผู้ใช้เลือกจากรายการผลลัพธ์ ระบบจะนับการเลือกเป็น และคำขอทั้งหมดที่ทำในระหว่างการค้นหาจะรวมอยู่ด้วยกัน และ จะนับเป็นคำขอเดียว หากผู้ใช้เลือกสถานที่ คำค้นหาจะเป็น ให้บริการแบบไม่มีค่าใช้จ่าย และจะเรียกเก็บเงินเฉพาะคำขอข้อมูลสถานที่เท่านั้น หากผู้ใช้ไม่ได้สร้าง ภายในสองสามนาทีหลังจากเริ่มเซสชัน เฉพาะ คำค้นหาจะถูกเรียกเก็บเงิน

จากมุมมองของแอป การดำเนินเหตุการณ์จะมีลักษณะดังนี้

  1. ผู้ใช้เริ่มพิมพ์ข้อความค้นหาเพื่อค้นหา "ปารีส ฝรั่งเศส"
  2. เมื่อตรวจพบข้อมูลจากผู้ใช้ แอปจะสร้างเซสชันใหม่ โทเค็น "โทเค็น A"
  3. ตามที่ผู้ใช้พิมพ์ API จะส่งคําขอเติมข้อความอัตโนมัติทุกๆ 2-3 ซึ่งจะแสดงรายการใหม่ของผลการค้นหาที่เป็นไปได้สำหรับแต่ละรายการ:
    "พ"
    "พาร์"
    "ปารีส"
    "ปารีส Fr"
  4. สิ่งที่จะเกิดขึ้นเมื่อผู้ใช้เลือก
    • คำขอทั้งหมดที่เกิดจากการค้นหาจะได้รับการจัดกลุ่มและเพิ่มลงใน แสดงด้วย "โทเค็น A" เป็นคำขอเดียว
    • การเลือกของผู้ใช้จะนับเป็นคำขอรายละเอียดสถานที่ และเพิ่ม กับเซสชันที่แสดงด้วย "โทเค็น A"
  5. เซสชันสิ้นสุดลง และแอปทิ้ง "โทเค็น 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();
index.ts

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();
index.js

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;
}

style.css

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>
index.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;
index.ts

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;
index.js

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;
}

style.css

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>
index.html

ลองใช้ตัวอย่าง