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

מבוא

ההשלמה האוטומטית היא תכונה של ספריית המקומות ב-Maps JavaScript API. אתם יכולים להשתמש בהשלמה האוטומטית כדי לתת לאפליקציות שלכם את התנהגות החיפוש של שדה החיפוש במפות Google. שירות ההשלמה האוטומטית יכול להתאים למילים מלאות ולמחרוזות משנה, ולפתור שמות של מקומות, כתובות וplus codes. לכן, אפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקלידים, כדי לספק תחזיות של מקומות בזמן אמת. בהתאם להגדרה של 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 מופיע ברשימה, סימן שהכול מוכן. אם ה-API לא מופיע ברשימה, מפעילים אותו:
   1. בחלק העליון של הדף, בוחרים באפשרות ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני, לוחצים על ספרייה.
   2. מחפשים את Places API ובוחרים אותו מרשימת התוצאות.
   3. לוחצים על הפעלה. בסיום התהליך, Places API יופיע ברשימת ממשקי ה-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 כדי לאחזר תוצאות של השלמה אוטומטית באופן פרוגרמטי (ראו במסמך העזרה של Maps JavaScript API: הקלאס 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. יש להעביר כמה מדינות כרשימה של קודי מדינות.

    הערה: אם מופיעות תוצאות לא צפויות עם קוד מדינה, צריך לוודא שאתם משתמשים בקוד שכולל את המדינות, הטריטוריות התלויות ואזורי העניין הגיאוגרפי המיוחדים שבהם אתם רוצים לטרגט. אפשר למצוא מידע על הקודים בWikipedia: List of ISO 3166 country codes או בISO Online Browsing Platform.

  • אפשר להשתמש ב-placeIdOnly כדי להורות לווידג'ט Autocomplete לאחזר רק מזהי מקומות. כשמפעילים את getPlace() באובייקט Autocomplete, באובייקט PlaceResult שזמין יהיו מוגדרים רק המאפיינים place id,‏ types ו-name. אפשר להשתמש במזהה המקום שהוחזר בקריאות לשירותים 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 שמועברים למבנה הווידג'ט, כפי שמוצג בדוגמה הקודמת, או קוראים ל-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 מPlace Types. אפשר לציין רק ערך אחד מטבלה 3.

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

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

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

כניסה לדמו

אחזור פרטי מקום

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

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

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

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

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

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

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

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

במאמר עיצוב הווידג'טים של ההשלמה האוטומטית ושל תיבת החיפוש מוסבר איך להתאים אישית את המראה של הווידג'טים.

הוספת ווידג'ט 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

להצגת דוגמה

במאמר עיצוב הווידג'טים של ההשלמה האוטומטית ושל תיבת החיפוש מוסבר איך להתאים אישית את המראה של הווידג'טים.

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

כדי לאחזר תחזיות באופן פרוגרמטי, משתמשים במחלקה 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(). במקרה כזה, הבקשה להשלמה אוטומטית משולבת עם הבקשה לפרטים על המקום, והחיוב על הקריאה מתבצע כבקשה רגילה לפרטים על המקום. אין חיוב על הבקשה להשלמה האוטומטית.

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

בדוגמה הבאה מוצגת יצירת אסימון סשן, ולאחר מכן העברה שלו ב-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);

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

מידע נוסף על אסימוני סשן

עיצוב של הווידג'טים של ההשלמה האוטומטית ושל SearchBox

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

מגבלות ושימוש במדיניות

מכסות

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

מדיניות

השימוש ב-Places Library, ‏ Maps JavaScript API חייב להתבצע בהתאם למדיניות שמפורטת לגבי Places API.