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

מבוא

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

תחילת העבודה

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

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

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

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

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

<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 יש להעביר כמה מדינות כרשימה של קודי מדינות.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

autocomplete.setBounds(newBounds);
index.ts

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

autocomplete.setBounds(newBounds);
index.js

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

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

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

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

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

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

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

להצגת דוגמה

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

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

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

להצגת דוגמה

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

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

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

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

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

  או:

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

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

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

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

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

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

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

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

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

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

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

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

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

להצגת דוגמה

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

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

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

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

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

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

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

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

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

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

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

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

מכסות

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

מדיניות

השימוש בספריית המקומות, Maps JavaScript API חייב להיות בהתאם המדיניות שמתוארת ל-Places API.