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

מבוא

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

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

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

הגדרת אפשרויות בזמן יצירת האובייקט

הבונה 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

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

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

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

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

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

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

בדוגמה הבאה מוצגת יצירה של אסימון סשן, ואז העברה שלו ב-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) widget, ב-Places SDK for Android Place Autocomplete (Legacy) widget או ב-Places SDK for iOS Place Autocomplete (Legacy) UI control.
• כדאי להבין מההתחלה את שדות הנתונים החיוניים של Place Autocomplete (גרסה קודמת).
• השדות 'הטיה לפי מיקום' ו'הגבלת מיקום' הם אופציונליים, אבל יכולה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
• כדאי להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה תפעל בצורה תקינה גם אם ממשק ה-API יחזיר שגיאה.
• חשוב לוודא שהאפליקציה מטפלת במקרים שבהם לא מתבצעת בחירה, ומציעה למשתמשים דרך להמשיך.

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

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

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

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

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

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

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

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

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

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

מגבלות שימוש

מכסות

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