השלמה אוטומטית למקומות

מבוא

ההשלמה האוטומטית היא תכונה של ספריית המקומות ב-Maps JavaScript API. אתם יכולים להשתמש בהשלמה אוטומטית כדי להוסיף לאפליקציות שלכם את ההתנהגות של שדה החיפוש במפות Google, שמאפשרת להקליד מונח חיפוש ולראות תוצאות בזמן ההקלדה. שירות ההשלמה האוטומטית יכול להתאים מילים מלאות ותת-מחרוזות, ולפתור שמות של מקומות, כתובות וקודי פלוס. לכן, אפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקליד, כדי לספק תחזיות של מקומות תוך כדי הקלדה. כפי שמוגדר ב-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 (חדש).

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

שירות המקומות הוא ספרייה עצמאית, נפרדת מהקוד הראשי של Maps JavaScript API. כדי להשתמש בתכונות שכלולות בספרייה הזו, צריך קודם לטעון אותה באמצעות הפרמטר libraries בכתובת ה-URL של bootstrap של 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 כדי לאחזר תוצאות של השלמה אוטומטית באופן פרוגרמטי (ראו את ההפניה אל Maps JavaScript API: מחלקה AutocompleteService).

בהמשך מופיע סיכום של השיעורים הזמינים:

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

  

  

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

  

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

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

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

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

• אלמנט input HTML מסוג 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, האובייקט PlaceResult שמוחזר יכלול רק את המאפיינים place id, types ו-name. אפשר להשתמש במזהה המקום שמוחזר בקריאות לשירותים Places, ‏ Geocoding, ‏ Directions או Distance Matrix.

הגבלת ההצעות להשלמה אוטומטית

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

הגדרת אפשרויות במהלך הבנייה

הבונה 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 שמועבר לקונסטרוקטור של הווידג'ט, כמו בדוגמה הקודמת, או קוראים ל-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.

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

• ציינתם יותר מחמישה סוגים.
• אתם מציינים סוגים לא מוכרים.
• אפשר לשלב בין כל סוגי המסננים מטבלה 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.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!">

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

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

הוספה של ווידג'ט תיבת חיפוש

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

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

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

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

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

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

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

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

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

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

שתי השיטות שלמעלה מחזירות מערך של אובייקטים של חיזוי מהצורה הבאה:

• ‫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 או אם משתמשים מחדש באסימון סשן, הסשן יחויב כאילו לא סופק אסימון סשן (כל בקשה מחויבת בנפרד).

אפשר להשתמש באותו טוקן סשן כדי לשלוח בקשה אחת של פרטי מקום לגבי המקום שמתקבל כתוצאה מקריאה ל-AutocompleteService.getPlacePredictions(). במקרה כזה, בקשת ההשלמה האוטומטית משולבת עם בקשת 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 מעוצבים כך שיתאימו להצגה במפות Google. אולי תרצו לשנות את הסגנון כדי שיתאים לאתר שלכם. אלה מחלקות ה-CSS שזמינות. כל הסוגים שמפורטים בהמשך רלוונטיים לווידג'טים Autocomplete ו-SearchBox.

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

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

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

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

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

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

כדי לייעל את העלות של השימוש בשירות Place Autocomplete (Legacy), כדאי להשתמש במסכות שדות בווידג'טים Place Details (Legacy) ו-Place Autocomplete (Legacy) כדי להחזיר רק את שדות הנתונים של Place Autocomplete (Legacy) שאתם צריכים.

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

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

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

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

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

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

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

הטיה של מיקום

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

הגבלת מיקום

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

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

מגבלות שימוש

מכסות

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