‫ Places UI Kit: ספרייה מוכנה לשימוש שמאפשרת למפתחים להתאים אישית ולשלוט. כדאי לנסות ולשתף את המשוב שלך על חוויית השימוש בערכת ממשק המשתמש.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

מפתחים באזור הכלכלי האירופי (EEA)

הערה: ספריות בצד השרת

בדף הזה נסביר על ספריית צד הלקוח שזמינה ב-Maps JavaScript API. אם אתם רוצים לעבוד עם שירות האינטרנט של Places API בשרת שלכם, כדאי לעיין בלקוח Node.js עבור Google Maps Services. בדף בקישור הזה יש גם מבוא ללקוח Java, ללקוח Python וללקוח Go לשירותי מפות Google.

מבוא

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

תחילת העבודה

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

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

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

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

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

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

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

סיכום הכיתות

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

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

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

איור 1: שדה טקסט עם השלמה אוטומטית ורשימת בחירה

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

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

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

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

הבונה 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.
  הערה: המאפיין name יכיל את הערך description מהחיזויים של השלמה אוטומטית של מקומות. מידע נוסף על description מופיע במאמרי העזרה של AutocompleteService.
  
  הודעה: הוצאנו משימוש את placeIdOnly ב-15 בינואר 2019, והוא יושבת ב-15 בינואר 2020. במקום זאת, משתמשים במערך fields בממשק AutocompleteOptions: fields: ['place_id', 'name', 'types'].

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

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

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

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

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

TypeScript

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

JavaScript

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

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

הערה: אם לא מציינים גבולות או אזור תצוגה במפה, ה-API ינסה לזהות את מיקום המשתמש מכתובת ה-IP שלו, ויטה את התוצאות למיקום הזה. כדאי להגדיר גבולות כשזה אפשרי. אחרת, משתמשים שונים עשויים לקבל תחזיות שונות. כדי לשפר את התחזיות באופן כללי, חשוב לספק אזור תצוגה הגיוני, למשל אזור תצוגה שמוגדר על ידי הזזה או שינוי מרחק התצוגה במפה, או אזור תצוגה שמוגדר על ידי מפתח על סמך מיקום המכשיר והרדיוס. אם רדיוס אינו זמין, 5 ק"מ נחשב לברירת מחדל סבירה עבור השלמה אוטומטית למקומות. אל תגדירו אזור תצוגה עם רדיוס אפס (נקודה אחת), אזור תצוגה שרוחבו כמה מטרים בלבד (פחות מ-100 מ') או אזור תצוגה שמשתרע על פני כל כדור הארץ.

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

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

TypeScript

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

JavaScript

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

TypeScript

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

JavaScript

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

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

TypeScript

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

JavaScript

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

לדוגמה

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

TypeScript

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

JavaScript

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. כדי לקבל פרטים על מקום:

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

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

חשוב: לא מומלץ להשתמש בהשלמה אוטומטית כדי לרענן מזהי מקומות, כי כל סשן יחויב. במקום זאת, קוראים ל-getDetails() ומציינים רק את השדה place_id.

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

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

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

TypeScript

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

JavaScript

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

לדוגמה

יכול להיות שרכיב הכתובת street_number לא יופיע בתשובות של Place Details עבור מזהי מקומות בחלק מההשלמות האוטומטיות. בדרך כלל זה קורה כשאי אפשר לבצע אינטרפולציה של הכתובת למקום. במקרים כאלה, המערך types של התחזית יכיל את הערך route. לחיזויים להשלמה אוטומטית עם מספר בתיאור (שאילתת הקלט תואמת), התגובה של Place Details למזהה המקום מכילה את המספר ברחוב רק אם המערך types של החיזוי מכיל לפחות אחד מהערכים הבאים:

street_address
הנחת יסוד
establishment

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

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

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

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

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

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

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

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

אלמנט 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 קיים, קוראים ל-setBounds() באובייקט SearchBox ומעבירים את האובייקט הרלוונטי LatLngBounds.

לדוגמה

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

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

TypeScript

// 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

JavaScript

// 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 הוא המונח התואם.

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

TypeScript

// 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

JavaScript

// 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

CSS

style.css

HTML

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

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

לדוגמה

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

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

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

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

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

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

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

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

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

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

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

איור גרפי של מחלקות ה-CSS של הווידג'טים Autocomplete ו-SearchBox — מחלקות CSS לווידג'טים של השלמה אוטומטית ושל תיבת חיפוש

מחלקת CSS	תיאור
`pac-container`	הרכיב החזותי שמכיל את רשימת החיזויים שמוחזרים על ידי שירות ההשלמה האוטומטית למקומות. הרשימה הזו מופיעה כתפריט נפתח מתחת לווידג'ט `Autocomplete` או `SearchBox`.
`pac-icon`	הסמל שמוצג מימין לכל פריט ברשימת התחזיות.
`pac-item`	פריט ברשימת התחזיות שמוצגת בווידג'ט `Autocomplete` או `SearchBox`.
`pac-item:hover`	הפריט כשמעבירים את סמן העכבר מעליו.
`pac-item-selected`	הפריט כשהמשתמש בוחר אותו באמצעות המקלדת. הערה: הפריטים שנבחרו יהיו חברים בכיתה הזו ובכיתה `pac-item`.
`pac-item-query`	תג span בתוך תג `pac-item` שהוא החלק העיקרי של התחזית. למיקומים גיאוגרפיים, הערך הזה מכיל שם מקום, כמו 'סידני', או שם רחוב ומספר, כמו '10 King Street'. בחיפושים מבוססי-טקסט כמו 'פיצה בניו יורק', הוא מכיל את הטקסט המלא של השאילתה. כברירת מחדל, הצבע של `pac-item-query` הוא שחור. אם יש טקסט נוסף ב-`pac-item`, הוא נמצא מחוץ ל-`pac-item-query` ומקבל את הסגנון שלו מ-`pac-item`. כברירת מחדל, הוא צבוע באפור. הטקסט הנוסף הוא בדרך כלל כתובת.
`pac-matched`	החלק בתחזית שהוחזרה שתואם לקלט של המשתמש. כברירת מחדל, הטקסט התואם מודגש בטקסט מודגש. הערה: הטקסט התואם יכול להיות בכל מקום בתוך `pac-item`. הוא לא בהכרח חלק מ-`pac-item-query`, ויכול להיות שהוא חלקית בתוך `pac-item-query` וגם חלקית בטקסט שנותר ב-`pac-item`.

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

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

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

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

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

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

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

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

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

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

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

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

כן, צריך עוד פרטים

שימוש ב-השלמה אוטומטית למקומות (מדור קודם) מבוסס-סשן עם Place Details (מדור קודם)
מכיוון שהאפליקציה שלך דורשת Place Details (מדור קודם), כמו שם המקום, הסטטוס של העסק, או שעות פעילות, ההטמעה של השלמה אוטומטית למקומות (מדור קודם) צריכה להשתמש בטוקן לסשן (באופן פרוגרמטי או מובנה בווידג'טים של JavaScript, Android, או iOS ) לכל סשן בנוסף למק"טים הרלוונטיים של Places Data, בהתאם לשדות הנתונים של המקום שאתה מבקש.¹

הטמעה של ווידג'טים
ניהול הסשנים מוטמע אוטומטית בווידג'טים של JavaScript, Android, או iOS. הגדרה זו כוללת גם בקשות של השלמה אוטומטית למקומות (מדור קודם) וגם בקשות של Place Details (מדור קודם) לגבי החיזוי שנבחר. חשוב לציין את הפרמטר fields כדי לוודא שאתם מבקשים רק את שדות הנתונים שאתם צריכים ב-השלמה אוטומטית למקומות (גרסה קודמת).

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

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

לא, צריך רק כתובת ומיקום

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

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

האם המשתמשים שלכם בוחרים חיזוי של השלמה אוטומטית למקומות (מדור קודם) בארבע בקשות או פחות, בממוצע?

כן

מטמיעים את השלמה אוטומטית למקומות (מדור קודם) באופן פרוגרמטי בלי אסימוני סשן, ומפעילים את Geocoding API על החיזוי של המקום שנבחר.
‫Geocoding API מספק כתובות וקואורדינטות של קו רוחב וקו אורך. ביצוע ארבע בקשות של Autocomplete - Per Request וקריאה אחת ל-Geocoding API לגבי החיזוי של המקום שנבחר, יעלה פחות מהעלות של השלמה אוטומטית למקומות (מדור קודם) לכל סשן.¹

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

לא

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

הטמעה של ווידג'טים
ניהול הסשנים מוטמע אוטומטית בווידג'טים של JavaScript, Android, או iOS. הגדרה זו כוללת גם בקשות של השלמה אוטומטית למקומות (גרסה קודמת) וגם בקשות של Place Details (גרסה קודמת) לגבי החיזוי שנבחר. כדי לוודא שאתם מבקשים רק את השדות שאתם צריכים, הקפידו לציין את הפרמטר fields.

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

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

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

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

למידע על עלויות, אפשר לעיין במחירונים של Google Maps Platform.

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

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

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

הטיה של מיקום

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

אזהרה: אם לא מציינים את הפרמטר radius, המערכת מתעלמת מהפרמטר location.

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

הגבלת מיקום

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

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

מכסות שימוש

מכסות

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

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

מבוא

תחילת העבודה

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

סיכום הכיתות

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

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

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

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

TypeScript

JavaScript

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

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

TypeScript

JavaScript

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

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

TypeScript

JavaScript

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

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

שינוי אזור החיפוש בתיבת החיפוש

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

TypeScript

JavaScript

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

TypeScript

JavaScript

CSS

HTML

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

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

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

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

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

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

כן, צריך עוד פרטים

לא, צריך רק כתובת ומיקום

כן

לא

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

הטיה של מיקום

הגבלת מיקום

מכסות שימוש

מכסות

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