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

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

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

מבוא

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

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

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

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

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

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

דוגמה לניסיון

JSFiddle.net Google Cloud Shell

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

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

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

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

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

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

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

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

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

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

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

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

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

מחלקת 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: השלמה אוטומטית – תמחור לפי בקשה ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום Place Details (מדור קודם). תמחור לפי בקשה בשילוב עם Geocoding API הוא חסכוני יותר מתמחור לפי סשן (מבוסס-סשן) אם מתקיימים שני התנאים הבאים:

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

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

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

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

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

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

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

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

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

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

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

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

כן

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

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

לא

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

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

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

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

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

דוגמה לניסיון

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

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

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

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

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

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

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

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

כן

לא

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

הטיה של מיקום

הגבלת מיקום

מכסות שימוש

מכסות

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