השלמה אוטומטית למקומות (דור קודם)

מבוא

השלמה אוטומטית היא תכונה של ספריית המקומות ב-Maps JavaScript API. אתם יכולים להשתמש בהשלמה האוטומטית כדי להוסיף לאפליקציות שלכם את התכונה "חיפוש תוך כדי הקלדה" של שדה החיפוש במפות Google. שירות ההשלמה האוטומטית יכול להתאים מילים מלאות ומחרוזות משנה, ולפתור שמות של מקומות, כתובות וקודי Plus Code. לכן, אפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקליד, כדי לספק חיזויים של מקומות בזמן אמת. לפי ההגדרה של Places API, "מקום" יכול להיות עסק, מיקום גיאוגרפי או נקודת עניין בולטת.

תחילת העבודה

לפני שמשתמשים בספריית המקומות ב-Maps JavaScript API, צריך לוודא ש-Places API מופעל במסוף Google Cloud, באותו פרויקט שהגדרתם ל-Maps JavaScript API.

כדי לראות את רשימת ממשקי ה-API שמופעלים:

1. נכנסים למסוף Google Cloud.
2. לוחצים על הכפתור Select a project, בוחרים את הפרויקט שהגדרתם ל-Maps JavaScript API ולוחצים על Open.
3. ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Places API.
4. אם ה-API מופיע ברשימה, אתם מוכנים. עם זאת, הפרויקט הזה נמצא בסטטוס "מדור קודם". במאמר מוצרים ותכונות מדור קודם מוסבר על שלב המוצרים מדור קודם ואיך עוברים מהם לשירותים חדשים יותר. יש חריגה אחת: הווידג'טים Autocomplete ו-SearchBox, שעדיין לא זמינים כמוצר GA ב-Places API (חדש).

טעינת הספרייה

שירות Places הוא ספרייה עצמאית, נפרדת מהקוד הראשי של Maps JavaScript API. כדי להשתמש בתכונות שכלולות בספרייה הזו, קודם צריך לטעון אותה באמצעות הפרמטר libraries בכתובת ה-URL ההתחלתית של Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

מידע נוסף זמין ב סקירה הכללית של הספריות.

סיכום הכיתות

ה-API מציע שני סוגים של ווידג'טים להשלמה אוטומטית, שאפשר להוסיף באמצעות המחלקות Autocomplete ו-SearchBox בהתאמה. בנוסף, אתם יכולים להשתמש במחלקה AutocompleteService כדי לאחזר תוצאות של השלמה אוטומטית באופן פרוגרמטי (ראו את מאמרי העזרה של ה-API של Maps JavaScript: המחלקה AutocompleteService).

הנה סיכום של המחלקות הזמינות:

• Autocomplete מוסיף שדה להזנת טקסט לדף האינטרנט, ומנטר את השדה הזה כדי לזהות הזנת תווים. כשהמשתמש מזין טקסט, ההשלמה האוטומטית מחזירה תחזיות של מקומות בצורה של רשימה נפתחת. כשהמשתמש בוחר מקום מהרשימה, מידע על המקום מוחזר לאובייקט ההשלמה האוטומטית, והאפליקציה יכולה לאחזר אותו. פרטים נוספים מופיעים בהמשך.

  

  

• SearchBox מוסיף שדה להזנת טקסט לדף האינטרנט, בדומה ל-Autocomplete. ההבדלים הם:
  • ההבדל העיקרי הוא בתוצאות שמופיעות ברשימת הבחירה. ‫SearchBox מספק רשימה מורחבת של חיזויים, שיכולה לכלול מקומות (כפי שהם מוגדרים ב-Places API) ומונחי חיפוש מוצעים. לדוגמה, אם המשתמש מזין "פיצה בתל", רשימת הבחירה עשויה לכלול את הביטוי "פיצה בתל אביב" וגם שמות של פיצריות שונות.
  • ב-SearchBox יש פחות אפשרויות להגבלת החיפוש מאשר ב-Autocomplete. במקרה הראשון, אפשר להטות את החיפוש לכיוון LatLngBounds נתון. במקרה השני, אפשר להגביל את החיפוש למדינה מסוימת ולסוגי מקומות מסוימים, וגם להגדיר את הגבולות. מידע נוסף זמין בהמשך.

  

  בהמשך מפורטים הפרטים.
• אתם יכולים ליצור אובייקט AutocompleteService כדי לאחזר חיזויים באופן פרוגרמטי. קוראים ל-getPlacePredictions() כדי לאחזר מקומות תואמים, או קוראים ל-getQueryPredictions() כדי לאחזר מקומות תואמים ומונחי חיפוש מוצעים. הערה: AutocompleteService לא מוסיף רכיבים אינטראקטיביים. במקום זאת, השיטות שלמעלה מחזירות מערך של אובייקטים מסוג חיזוי. כל אובייקט חיזוי מכיל את הטקסט של החיזוי, וגם מידע עזר ופרטים על האופן שבו התוצאה תואמת לקלט של המשתמש. פרטים נוספים מופיעים בהמשך.

הוספת ווידג'ט של השלמה אוטומטית

הווידג'ט Autocomplete יוצר שדה להזנת טקסט בדף האינטרנט, מספק חיזויים של מקומות ברשימת בחירה בממשק המשתמש ומחזיר פרטי מקומות בתגובה לבקשת getPlace(). כל רשומה ברשימת הבחירה תואמת למקום אחד (כפי שמוגדר ב-Places API).

ה-constructor של Autocomplete מקבל שני ארגומנטים:

• רכיב HTML input מסוג text. זהו השדה להזנת קלט ששירות ההשלמה האוטומטית יעקוב אחריו ויצרף אליו את התוצאות שלו.
• ארגומנט אופציונלי מסוג AutocompleteOptions, שיכול להכיל את המאפיינים הבאים:
  • מערך של נתונים מסוג fields שייכללו בתגובה של Place Details ל-PlaceResult שהמשתמש בחר. אם המאפיין לא מוגדר או אם מועבר הערך ['ALL'], כל השדות הזמינים מוחזרים ומחויבים (לא מומלץ לפריסות בסביבת ייצור). כאןPlaceResult מופיעה רשימה של שדות.
  • מערך של types שמציין סוג מפורש או אוסף של סוגים, כמו שמפורט בסוגים הנתמכים. אם לא מציינים סוג, כל הסוגים מוחזרים.
  • ‫bounds הוא אובייקט google.maps.LatLngBounds שמציין את האזור שבו מחפשים מקומות. התוצאות מוטות לכיוון מקומות שנמצאים בתוך הגבולות האלה, אבל לא מוגבלות אליהם.
  • ‫strictBounds הוא ערך boolean שמציין אם ה-API צריך להחזיר רק את המקומות שנמצאים בדיוק באזור שמוגדר על ידי bounds. ה-API לא מחזיר תוצאות מחוץ לאזור הזה, גם אם הן תואמות לקלט של המשתמש.
  • אפשר להשתמש ב-componentRestrictions כדי להגביל את התוצאות לקבוצות ספציפיות. אפשר להשתמש ב-componentRestrictions כדי לסנן לפי עד 5 מדינות. המדינות צריכות להיות מועברות כקוד מדינה בן שני תווים, שתואם לתקן ISO 3166-1 Alpha-2. כדי להעביר כמה מדינות, צריך להעביר רשימה של קודי מדינות.

    הערה: אם אתם מקבלים תוצאות לא צפויות עם קוד מדינה, ודאו שאתם משתמשים בקוד שכולל את המדינות, הטריטוריות התלויות והאזורים המיוחדים בעלי העניין הגיאוגרפי שאתם מתכוונים אליהם. מידע על הקודים זמין בויקיפדיה: רשימת קודי מדינות לפי תקן ISO 3166 או בפלטפורמת הגלישה אונליין של ISO.

  • אפשר להשתמש ב-placeIdOnly כדי להורות לווידג'ט Autocomplete לאחזר רק מזהי מקומות. כשמפעילים את getPlace() באובייקט Autocomplete, המאפיינים place id,‏ types ו-name יהיו היחידים שיוגדרו ב-PlaceResult שיהיה זמין. אפשר להשתמש במזהה המקום שמוחזר בקריאות לשירותים Places, ‏ Geocoding, ‏ Directions או Distance Matrix.

הגבלת ההצעות להשלמת החיפוש

כברירת מחדל, ההשלמה האוטומטית למקומות מציגה את כל סוגי המקומות, עם הטיה לחיזויים קרוב למיקום של המשתמש, ומאחזרת את כל שדות הנתונים הזמינים של המקום שהמשתמש בחר. הגדירו את האפשרויות של השלמה אוטומטית למקומות כדי להציג תחזיות רלוונטיות יותר בהתאם לתרחיש לדוגמה.

הגדרת אפשרויות בזמן הבנייה

ה-constructor של Autocomplete מקבל פרמטר AutocompleteOptions כדי להגדיר אילוצים בזמן יצירת הווידג'ט. בדוגמה הבאה, האפשרויות bounds,‏ componentRestrictions ו-types מוגדרות כדי לבקש מקומות מסוג establishment, תוך מתן עדיפות למקומות שנמצאים באזור הגיאוגרפי שצוין והגבלת החיזויים רק למקומות בארצות הברית. האפשרות fields מציינת איזה מידע להחזיר על המקום שהמשתמש בחר.

קוראים ל-setOptions() כדי לשנות ערך של אפשרות בווידג'ט קיים.

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

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

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

ציון שדות נתונים

כדי להימנע מחיוב על מק"טים של נתוני מקומות שאתם לא צריכים, אתם יכולים לציין שדות נתונים. מוסיפים את המאפיין fields ל-AutocompleteOptions שמועברים ל-constructor של הווידג'ט, כמו בדוגמה הקודמת, או קוראים ל-setFields() באובייקט Autocomplete קיים.

autocomplete.setFields(["place_id", "geometry", "name"]);

הגדרת הטיות וגבולות של אזור החיפוש להשלמה אוטומטית

אתם יכולים להטות את תוצאות ההשלמה האוטומטית כך שיעדיפו מיקום או אזור משוערים, בדרכים הבאות:

• מגדירים את הגבולות ביצירת האובייקט Autocomplete.
• שינוי הגבולות של Autocomplete קיים.
• מגדירים את הגבולות של אזור התצוגה במפה.
• הגבלת החיפוש לגבולות.
• להגביל את החיפוש למדינה ספציפית.

בדוגמה הקודמת מוסבר איך להגדיר גבולות בזמן היצירה. הדוגמאות הבאות ממחישות את הטכניקות האחרות של הטיה.

שינוי הגבולות של השלמה אוטומטית קיימת

מפעילים את setBounds() כדי לשנות את אזור החיפוש של Autocomplete קיים לגבולות מלבניים.

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
index.ts

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
index.js

הגדרת הגבולות לאזור התצוגה של המפה

אפשר להשתמש ב-bindTo() כדי להטות את התוצאות לאזור התצוגה של המפה, גם כשאזור התצוגה משתנה.

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

משתמשים ב-unbind() כדי לבטל את הקישור של הצעות להשלמת החיפוש לאזור התצוגה של המפה.

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.ts

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

להצגת דוגמה

הגבלת החיפוש לגבולות הנוכחיים

מגדירים את האפשרות strictBounds כדי להגביל את התוצאות לגבולות הנוכחיים, על סמך אזור התצוגה במפה או גבולות מלבניים.

autocomplete.setOptions({ strictBounds: true });

הגבלת התחזיות למדינה ספציפית

משתמשים באפשרות componentRestrictions או קוראים ל-setComponentRestrictions() כדי להגביל את החיפוש של ההשלמה האוטומטית לקבוצה ספציפית של עד חמש מדינות.

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.ts

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});
index.js

להצגת דוגמה

הגבלת סוגי המקומות

כדי להגביל את החיזויים לסוגי מקומות מסוימים, משתמשים באפשרות types או קוראים ל-setTypes(). האילוץ הזה מציין סוג או אוסף סוגים, כמו שמפורט בסוגי מקומות. אם לא מציינים אילוץ, כל הסוגים מוחזרים.

בערך של האפשרות types או בערך שמועבר אל setTypes(), אפשר לציין:

• מערך שמכיל עד חמישה ערכים מטבלה 1 או מטבלה 2 בקטע סוגי מקומות. לדוגמה:

  types: ['hospital', 'pharmacy', 'bakery', 'country']

  או:

  autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);

• מסנן אחד כלשהו בטבלה 3 מתוך סוגי מקומות. אפשר לציין רק ערך אחד מטבלה 3.

הבקשה תידחה אם:

• ציינתם יותר מ-5 סוגים.
• אתם מציינים סוגים לא מזוהים.
• אתם יכולים לשלב כל סוג מטבלה 1 או מטבלה 2 עם כל מסנן מטבלה 3.

ההדגמה של ההשלמה האוטומטית למקומות ממחישה את ההבדלים בין סוגי המקומות השונים.

לצפייה בהדגמה

קבלת מידע על מקומות

כשמשתמש בוחר מקום מההצעות שמוצגות בשדה הטקסט של ההשלמה האוטומטית, השירות מפעיל אירוע place_changed. כדי לקבל פרטים על מקום:

1. יוצרים גורם מטפל באירועים לאירוע place_changed, וקוראים ל-addListener() באובייקט Autocomplete כדי להוסיף את הגורם המטפל.
2. מפעילים את Autocomplete.getPlace() באובייקט Autocomplete כדי לאחזר אובייקט PlaceResult, שבו אפשר להשתמש כדי לקבל מידע נוסף על המקום שנבחר.

כברירת מחדל, כשמשתמש בוחר מקום, ההשלמה האוטומטית מחזירה את כל שדות הנתונים שזמינים למקום שנבחר, ואתם מחויבים בהתאם. משתמשים ב-Autocomplete.setFields() כדי לציין אילו שדות נתונים של מקומות להחזיר. מידע נוסף על האובייקט PlaceResult, כולל רשימה של שדות נתונים של מקומות שאפשר לבקש. כדי להימנע מתשלום על נתונים שאתם לא צריכים, הקפידו להשתמש ב-Autocomplete.setFields() כדי לציין רק את נתוני המקומות שבהם תשתמשו.

המאפיין name מכיל את הערך description מההצעות להשלמה אוטומטית של מקומות. מידע נוסף על description זמין במסמכי התיעוד של Places Autocomplete.

בטפסים של כתובות, כדאי לקבל את הכתובת בפורמט מובנה. כדי להחזיר את הכתובת המובנית של המקום שנבחר, מפעילים את Autocomplete.setFields() ומציינים את השדה address_components.

בדוגמה הבאה, המילוי האוטומטי משמש למילוי השדות בטופס כתובת.

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}
index.ts

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;
index.js

להצגת דוגמה

התאמה אישית של הטקסט לדוגמה

כברירת מחדל, שדה הטקסט שנוצר על ידי שירות ההשלמה האוטומטית מכיל טקסט לדוגמה סטנדרטי. כדי לשנות את הטקסט, מגדירים את המאפיין placeholder ברכיב input:

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

הערה: הטקסט לדוגמה שמוגדר כברירת מחדל מותאם לשפה באופן אוטומטי. אם אתם מציינים ערך זמני משלכם לשמירת מקום (פלייסהולדר), אתם צריכים לטפל בלוקליזציה של הערך הזה באפליקציה. במאמר בנושא לוקליזציה מוסבר איך Google Maps JavaScript API בוחר את השפה שבה הוא משתמש.

כדי להתאים אישית את מראה הווידג'ט, אפשר לעיין במאמר עיצוב הווידג'טים Autocomplete ו-SearchBox.

הוספה של ווידג'ט SearchBox

SearchBox מאפשר למשתמשים לבצע חיפוש גיאוגרפי מבוסס-טקסט, כמו "פיצה בתל אביב" או "חנויות נעליים ליד רחוב דיזנגוף". אפשר לצרף את SearchBox לשדה טקסט, וכשמזינים טקסט, השירות מחזיר חיזויים בצורת רשימה נפתחת.

‫SearchBox מספק רשימה מורחבת של חיזויים, שיכולה לכלול מקומות (כפי שהוגדרו על ידי Places API) וגם הצעות למונחי חיפוש. לדוגמה, אם המשתמש מזין "פיצה בתל", רשימת הבחירה עשויה לכלול את הביטוי "פיצה בתל אביב" וגם שמות של פיצריות שונות. כשהמשתמש בוחר מקום מהרשימה, המידע על המקום הזה מוחזר לאובייקט SearchBox, והאפליקציה יכולה לאחזר אותו.

ה-constructor של SearchBox מקבל שני ארגומנטים:

• רכיב HTML input מסוג text. זהו השדה להזנת קלט שהשירות SearchBox יעקוב אחריו ויצרף אליו את התוצאות שלו.
• ארגומנט options, שיכול להכיל את המאפיין bounds: bounds הוא אובייקט google.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 קיים, מפעילים את setBounds() באובייקט SearchBox ומעבירים את האובייקט LatLngBounds הרלוונטי.

להצגת דוגמה

קבלת מידע על מקומות

כשהמשתמש בוחר פריט מהתחזיות שמצורפות לתיבת החיפוש, השירות מפעיל אירוע places_changed. אפשר להפעיל את getPlaces() באובייקט SearchBox כדי לאחזר מערך שמכיל כמה חיזויים, שכל אחד מהם הוא אובייקט PlaceResult.

למידע נוסף על האובייקט PlaceResult, עיינו במסמכי התיעוד בנושא תוצאות של פרטי מקום.

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

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

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

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      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,
        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);
});
index.ts

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

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

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

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const 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,
        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);
});
index.js

להצגת דוגמה

כדי להתאים אישית את מראה הווידג'ט, אפשר לעיין במאמר עיצוב הווידג'טים Autocomplete ו-SearchBox.

אחזור פרוגרמטי של חיזויים של שירות ההשלמה האוטומטית למקומות

כדי לאחזר תחזיות באופן פרוגרמטי, משתמשים במחלקה AutocompleteService. ‫AutocompleteService לא מוסיף רכיבים אינטראקטיביים. במקום זאת, היא מחזירה מערך של אובייקטים של חיזוי, שכל אחד מהם מכיל את הטקסט של החיזוי, מידע על קובץ העזר ופרטים על האופן שבו התוצאה תואמת לקלט של המשתמש. האפשרות הזו שימושית אם אתם רוצים יותר שליטה בממשק המשתמש ממה שמציעים Autocomplete ו-SearchBox שמתוארים למעלה.

‫AutocompleteService חושף את השיטות הבאות:

• ‫getPlacePredictions() מחזירה חיזויים של מקומות. הערה: "מקום" יכול להיות עסק, מיקום גיאוגרפי או נקודת עניין בולטת, כפי שמוגדר ב-Places API.
• ‫getQueryPredictions() מחזירה רשימה מורחבת של חיזויים, שיכולה לכלול מקומות (כפי שהוגדרו על ידי Places API) ומונחי חיפוש מוצעים. לדוגמה, אם המשתמש מזין "פיצה בתל", רשימת הבחירה עשויה לכלול את הביטוי "פיצה בתל אביב" וגם שמות של פיצריות שונות.

שתי השיטות שלמעלה מחזירות מערך של אובייקטים מסוג prediction בפורמט הבא:

• ‫description הוא החיזוי התואם.
• ‫distance_meters הוא המרחק במטרים של המקום מהערך שצוין ב-AutocompletionRequest.origin.
• ‫matched_substrings מכיל קבוצה של מחרוזות משנה בתיאור שתואמות לרכיבים בקלט של המשתמש. המידע הזה שימושי אם רוצים להדגיש את מחרוזות המשנה האלה באפליקציה. במקרים רבים, השאילתה תופיע כמחרוזת משנה של שדה התיאור.
  • ‫length הוא אורך מחרוזת המשנה.
  • ‫offset הוא היסט התווים, שנמדד מתחילת מחרוזת התיאור, שבו מופיעה מחרוזת המשנה התואמת.
• ‫place_id הוא מזהה טקסטואלי שמזהה מקום באופן ייחודי. כדי לאחזר מידע על המקום, מעבירים את המזהה הזה בשדה placeId של בקשה לפרטי מקום. איך מפנים למקום באמצעות מזהה מקום
• ‫terms הוא מערך שמכיל רכיבים של השאילתה. במקרה של מקום, כל רכיב בדרך כלל יהיה חלק מהכתובת.
  • ‫offset הוא היסט התווים, שנמדד מתחילת מחרוזת התיאור, שבו מופיעה מחרוזת המשנה התואמת.
  • ‫value הוא המונח התואם.

בדוגמה הבאה, מתבצעת בקשה לחיזוי שאילתה עבור הביטוי "פיצה קרוב" והתוצאה מוצגת ברשימה.

// 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(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;
index.ts

// 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() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <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=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

להצגת דוגמה

טוקנים לסשנים

AutocompleteService.getPlacePredictions() יכול להשתמש בטוקנים לסשנים (אם הם הוטמעו) כדי לקבץ יחד בקשות להשלמה אוטומטית לצורכי חיוב. טוקנים לסשנים מקבצים את שלבי השאילתה והבחירה של חיפוש בהשלמה אוטומטית של משתמש לסשן נפרד לצורכי חיוב. הסשן מתחיל כשהמשתמש מתחיל להקליד שאילתה, ומסתיים כשהוא בוחר מקום. כל סשן יכול לכלול כמה שאילתות, ואחריהן בחירה של מקום אחד. אחרי שהסשן מסתיים, הטוקן כבר לא תקף. האפליקציה צריכה ליצור אסימון חדש לכל סשן. מומלץ להשתמש בטוקנים לסשנים בכל הסשנים של ההשלמה האוטומטית. אם הפרמטר sessionToken מושמט, או אם משתמשים שוב באותו טוקן לסשן, הסשן מחויב כאילו לא סופק טוקן לסשן (כל בקשה מחויבת בנפרד).

צריך להשתמש באותו טוקן לסשן כדי לשלוח בקשה אחת של Place Details לגבי המקום שמתקבל כתוצאה מקריאה ל-AutocompleteService.getPlacePredictions(). במקרה כזה, בקשת ההשלמה האוטומטית משולבת עם בקשת Place Details, והקריאה מחויבת כבקשת Place Details רגילה. אין חיוב על בקשת ההשלמה האוטומטית. אם לא תשתמשו בטוקן לסשן בבקשה, תחויבו גם על בקשת ההשלמה האוטומטית וגם על בקשת Place Details.

חשוב להעביר טוקן ייחודי לכל סשן חדש. אם תשתמשו באותו אסימון ביותר מסשן אחד של השלמה אוטומטית, הסשנים האלה של ההשלמה האוטומטית יבוטלו, וכל בקשת השלמה אוטומטית בסשנים הלא חוקיים תחויב בנפרד באמצעות מק"ט של השלמה אוטומטית לכל בקשה. מידע נוסף על טוקנים לסשנים

בדוגמה הבאה מוצגת יצירה של טוקן לסשן, ואז העברה שלו ב-AutocompleteService (הפונקציה displaySuggestions() הושמטה כדי לקצר):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

חשוב להעביר טוקן ייחודי לכל סשן חדש. אם תשתמשו באותו טוקן ליותר מסשן אחד, כל בקשה תחויב בנפרד.

מידע נוסף על טוקנים לסשנים

עיצוב הווידג'טים Autocomplete ו-SearchBox

כברירת מחדל, הרכיבים בממשק המשתמש שסופקו על ידי Autocomplete ו-SearchBox מעוצבים כך שיתאימו להכללה במפת Google. יכול להיות שתצטרכו לשנות את הסגנון כדי להתאים אותו לאתר שלכם. אפשר להשתמש במחלקות ה-CSS הבאות. כל המחלקות שמופיעות בהמשך רלוונטיות גם לווידג'ט Autocomplete וגם לווידג'ט SearchBox.

אופטימיזציה של השלמה אוטומטית למקומות (גרסה קודמת)

בקטע הזה מתוארות שיטות מומלצות שיעזרו לכם להפיק את המקסימום משירות ההשלמה האוטומטית למקומות (הגרסה הקודמת).

הנה כמה הנחיות כלליות:

• הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט השלמה אוטומטית למקומות (דור קודם) של Maps JavaScript API, בווידג'ט השלמה אוטומטית למקומות (דור קודם) של Places SDK ל-Android או ברכיב האינטראקטיבי השלמה אוטומטית למקומות (דור קודם) של Places SDK ל-iOS.
• חשוב להבין מהם שדות הנתונים החיוניים של השלמה אוטומטית למקומות (מדור קודם) כבר מההתחלה.
• השדות "העדפת מיקום" ו"הגבלת מיקום" הם אופציונליים, אבל יכולה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
• כדאי להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה תפעל בצורה תקינה אם ה-API יחזיר שגיאה.
• חשוב לוודא שהאפליקציה מטפלת במקרים שבהם אין בחירה ומציעה למשתמשים דרך להמשיך.

שיטות מומלצות לאופטימיזציה של עלויות

אופטימיזציה בסיסית של עלויות

כדי להוזיל את עלות השימוש בשירות "השלמה אוטומטית למקומות (דור קודם)", אתם יכולים להשתמש במסכות שדות בווידג'טים של "פרטי מקומות (דור קודם)" ו"השלמה אוטומטית למקומות (דור קודם)" כדי להחזיר רק את שדות הנתונים של "השלמה אוטומטית למקומות (דור קודם)" שאתם צריכים.

אופטימיזציה מתקדמת של עלויות

כדאי לשקול הטמעה פרוגרמטית של השלמה אוטומטית למקומות (מדור קודם) כדי לגשת אל מק"ט: השלמה אוטומטית – תמחור לכל בקשה ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום Place Details (מדור קודם). תמחור לכל בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לכל סשן (מבוסס-סשן) אם שני התנאים הבאים מתקיימים:

• אם אתם צריכים רק את קווי האורך והרוחב או את הכתובת של המקום שהמשתמש בחר, Geocoding API מספק את המידע הזה בעלות נמוכה יותר מאשר קריאה ל-Place Details (דור קודם).
• אם המשתמשים בוחרים הצעה להשלמת החיפוש מתוך ממוצע של ארבע בקשות להשלמה אוטומטית למקומות (דור קודם) או פחות, תמחור לפי בקשה יכול להיות משתלם יותר מתמחור לפי סשן.

האם האפליקציה שלכם דורשת מידע אחר מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?

שיטות מומלצות לשיפור הביצועים

בהנחיות הבאות מוסבר איך לשפר את הביצועים של השלמה אוטומטית למקומות (דור קודם):

• מוסיפים להטמעה של Place Autocomplete (מדור קודם) הגבלות לפי מדינה, הטיה לפי מיקום והעדפת שפה (להטמעות פרוגרמטיות). אין צורך בהעדפת שפה בווידג'טים, כי הם בוחרים את העדפות השפה מהדפדפן או מהמכשיר הנייד של המשתמש.
• אם השירות "השלמה אוטומטית למקומות (דור קודם)" מלווה במפה, אתם יכולים להטות את המיקום לפי אזור התצוגה של המפה.
• במקרים שבהם המשתמש לא בוחר באחת מההצעות של ההשלמה האוטומטית למקומות (מדור קודם), בדרך כלל כי אף אחת מההצעות האלה היא לא הכתובת הרצויה, אתם יכולים להשתמש שוב בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
  • אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, השתמשו שוב בקלט המקורי של המשתמש בקריאה ל-Geocoding API.
  • אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, השתמשו בבקשה ל-Place Details (מדור קודם). אם התוצאות צפויות רק באזור ספציפי, השתמשו בהטיית מיקום.
  תרחישים נוספים שבהם מומלץ להשתמש ב-Geocoding API:
  • משתמשים שמזינים כתובות של יחידות משנה, כמו כתובות של יחידות או דירות ספציפיות בתוך בניין. לדוגמה, הכתובת בצ'כיה "Stroupežnického 3191/17, Praha" מניבה חיזוי חלקי בהשלמה אוטומטית למקומות (מדור קודם).
  • משתמשים שמזינים כתובות עם קידומות של קטעי כביש, כמו "‎23-30 29th St, Queens" בניו יורק או "‎47-380 Kamehameha Hwy, Kaneohe" באי קאואיי שבהוואי.

הטיית מיקום

כדי להטות את התוצאות לאזור מסוים, מעבירים פרמטר location ופרמטר radius. ההגדרה הזו מנחה את ההשלמה האוטומטית למקומות (מדור קודם) להעדיף הצגת תוצאות בתוך האזור שהוגדר. יכול להיות שיוצגו תוצאות מחוץ לאזור שהוגדר. אפשר להשתמש בפרמטר includedRegionCodes כדי לסנן את התוצאות כך שיוצגו רק המקומות במדינה מסוימת.

הגבלת מיקום

כדי להגביל את התוצאות לאזור מסוים, צריך להעביר פרמטר locationRestriction.

אפשר גם להגביל את התוצאות לאזור שמוגדר על ידי location ופרמטר radius, על ידי הוספת הפרמטר strictbounds. ההגדרה הזו מנחה את ההשלמה האוטומטית למקומות (מדור קודם) להחזיר רק תוצאות באזור הזה.

מכסות שימוש

מכסות

למידע על מכסות ותמחור, עיינו ב מסמכי התיעוד בנושא שימוש וחיוב של Places API.