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

דף זה תורגם על ידי Cloud Translation API.

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

בחירת פלטפורמה: Android iOS JavaScript Web Service

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

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

מבוא

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

תחילת העבודה

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

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

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

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

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

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

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

סיכום הכיתות

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

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

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

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

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

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

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

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

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

אלמנט HTML מסוג input מסוג text. זהו שדה הקלט ששירות ההשלמה האוטומטית יעקוב אחריו ויצרף אליו את התוצאות שלו.
ארגומנט אופציונלי AutocompleteOptions, שיכול להכיל את המאפיינים הבאים:
- מערך נתונים fields שייכלל בתשובה Place Details עבור PlaceResult שנבחר על ידי המשתמש. אם המאפיין לא מוגדר או אם הערך ['ALL'] מועבר, כל השדות הזמינים יחזרו ויתבצע חיוב עליהם (לא מומלץ להשתמש באפשרות הזו לפריסות בסביבת הייצור). רשימה של שדות מופיעה במאמר PlaceResult.
- מערך של types שמציין סוג מפורש או אוסף סוגים, כפי שמפורט בסוגים הנתמכים. אם לא מציינים סוג, כל הסוגים יחזרו.
- bounds הוא אובייקט google.maps.LatLngBounds שמציין את האזור שבו רוצים לחפש מקומות. התוצאות מוטה לכיוון המקומות שנמצאים בתוך הגבולות האלה, אבל לא מוגבלת אליהם.
- strictBounds הוא boolean שמציין אם ה-API צריך להחזיר רק את המקומות שנמצאים בתוך האזור המוגדר על ידי bounds הנתון. ה-API לא מחזיר תוצאות מחוץ לאזור הזה, גם אם הן תואמות לקלט של המשתמש.
  הערה: הגבלת המיקום חלה רק על מסלולים שלמים. יכול להיות שתוצאות סינתטיות שנמצאות מחוץ להגבלת המיקום יוצגו על סמך מסלול שמצטלב עם הגבלת המיקום.
- אפשר להשתמש ב-componentRestrictions כדי להגביל את התוצאות לקבוצות ספציפיות. נכון לעכשיו, אפשר להשתמש ב-componentRestrictions כדי לסנן לפי עד 5 מדינות. צריך להעביר את המדינות כקוד מדינה בן שתי אותיות שתואם לתקן ISO 3166-1 Alpha-2. יש להעביר כמה מדינות כרשימה של קודי מדינות.
  הערה: אם מקבלים תוצאות לא צפויות עם קוד מדינה, צריך לוודא שמשתמשים בקוד שכולל את המדינות, הטריטוריות התלויות ואזורי העניין הגיאוגרפי הספציפיים הרצויים. אפשר למצוא מידע על הקודים בWikipedia: List of ISO 3166 country codes או בISO Online Browsing Platform.
- אפשר להשתמש ב-placeIdOnly כדי להורות לווידג'ט Autocomplete לאחזר רק מזהי מקומות. כשמפעילים את getPlace() באובייקט Autocomplete, באובייקט PlaceResult שזמין יהיו מוגדרים רק המאפיינים place id,‏ types ו-name. אפשר להשתמש במזהה המקום שהוחזר בקריאות לשירותים Places‏, Geocoding‏, Directions או Distance Matrix.
  הערה: הנכס name יכיל את הערך description מהחיזויים של Places להשלמה אוטומטית. מידע נוסף על description זמין במסמכי התיעוד של AutocompleteService.
  
  הערה: החל מ-15 בינואר 2019, הדומיין placeIdOnly הוצא משימוש והוא יושבת ב-15 בינואר 2020. במקום זאת, משתמשים במערך fields בממשק AutocompleteOptions: fields: ['place_id', 'name', 'types'].

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

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

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

ה-constructor של 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 מPlace Types. אפשר לציין רק ערך אחד מטבלה 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 זמין במסמכי העזרה בנושא השלמה אוטומטית של מקומות.

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

street_address
הנחת יסוד
מוסד

התאמה אישית של טקסט placeholder

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

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

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

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

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

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

איור גרפי של כיתות ה-CSS של הווידג'טים של ההשלמה האוטומטית ושל SearchBox — כיתות CSS לווידג'טים של השלמה אוטומטית ושל SearchBox

סיווג CSS	תיאור
`pac-container`	הרכיב החזותי שמכיל את רשימת התחזיות שהוחזרו על ידי השירות 'השלמה אוטומטית של מקומות'. הרשימה הזו מופיעה כרשימה נפתחת מתחת לווידג'ט `Autocomplete` או `SearchBox`.
`pac-icon`	הסמל שמופיע משמאל לכל פריט ברשימת התחזיות.
`pac-item`	פריט ברשימת התחזיות שסופקו על ידי הווידג'ט `Autocomplete` או `SearchBox`.
`pac-item:hover`	הפריט כשהמשתמש מעביר את סמן העכבר מעליו.
`pac-item-selected`	הפריט כאשר המשתמש בוחר בו באמצעות המקלדת. הערה: הפריטים שנבחרו יהיו חברים בכיתה הזו ובכיתה `pac-item`.
`pac-item-query`	טווח בתוך `pac-item` שהוא החלק העיקרי של התחזית. במיקומים גיאוגרפיים, השדה הזה מכיל שם מקום, כמו 'תל אביב', או שם רחוב ומספר, כמו 'רחוב בן גוריון 10'. בחיפושים מבוססי-טקסט, כמו 'פיצה בתל אביב', הוא מכיל את הטקסט המלא של השאילתה. כברירת מחדל, הערך של `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 מחזיר שגיאה.
חשוב לוודא שהאפליקציה מטפלת במקרים שבהם לא בוצעה בחירה ומציעה למשתמשים דרך להמשיך.

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

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

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

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

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

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

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

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

כן, נדרשים פרטים נוספים

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

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

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

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

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

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

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

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

כן

מטמיעים את ההשלמה האוטומטית של מקומות באופן פרוגרמטי בלי אסימוני סשן, ומפעילים את Geocoding API על תחזית המיקום שנבחרה.
Geocoding API מספק כתובות וקואורדינטות של קווי אורך ורוחב תמורת 0.005 $לכל בקשה. שליחת ארבע בקשות Place Autocomplete – Per Request עולה 0.01132$, כך שהעלות הכוללת של ארבע הבקשות וקריאה ל-Geocoding API לגבי תחזית המקום שנבחרה היא 0.01632$, נמוכה מהמחיר של השלמת האוטומטית 'לכל סשן', 0.017 $לכל סשן.¹

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

לא

שימוש בהשלמה אוטומטית של מקומות מבוססת-סשן עם פרטי מקומות
מאחר שמספר הבקשות הממוצע שאתם צפויים לשלוח לפני שמשתמש יבחר תחזית של Place Autocomplete חורג מהעלות של התמחור 'לסשן', בהטמעה של Place Autocomplete צריך להשתמש באסימון סשן גם לבקשות של Place Autocomplete וגם לבקשה המשויכת של פרטי המקום, בעלות כוללת של 0.017 $לסשן.¹

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

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

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

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

העלויות שמפורטות כאן הן בדולר ארה"ב. מידע מלא על התמחור זמין בדף חיוב בפלטפורמה של מפות Google.

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

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

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

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

מכסות

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

מדיניות

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

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

מבוא

תחילת העבודה

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

סיכום הכיתות

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

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

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

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

TypeScript

JavaScript

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

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

TypeScript

JavaScript

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

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

TypeScript

JavaScript

התאמה אישית של טקסט placeholder

הוספת ווידג'ט SearchBox

שינוי אזור החיפוש של SearchBox

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

TypeScript

JavaScript

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

TypeScript

JavaScript

CSS

HTML

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

אסימוני סשן

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

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

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

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

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

כן, נדרשים פרטים נוספים

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

כן

לא

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

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

מכסות

מדיניות