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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

מבוא

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

תחילת העבודה

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

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

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

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

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

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

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

סיכום השיעורים

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

לפניכם סיכום של השיעורים הזמינים:

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

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

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

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

  • רכיב input של HTML מסוג 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: רשימת קודי מדינה בתקן ISO 3166 או בפלטפורמת הגלישה באינטרנט של ISO.

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

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

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

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

ה-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);

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);

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

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

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

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

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

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

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

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

צריך להפעיל את 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);

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);
הגדרת הגבולות לאזור התצוגה של המפה

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

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

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

TypeScript

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

JavaScript

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

להצגת דוגמה

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

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

autocomplete.setOptions({ strictBounds: true });
הגבלת החיזויים למדינה ספציפית

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

TypeScript

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

JavaScript

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

להצגת דוגמה

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

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

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

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

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

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

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

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

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

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

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

הנכס 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();
}

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;

להצגת דוגמה

התאמה אישית של טקסט זמני אקראי

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

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

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

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

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

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

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

  • רכיב input של HTML מסוג text. זה השדה להזנת קלט שבו השירות SearchBox יעקוב ויצרף את התוצאות שלו.
  • ארגומנט options, שיכול להכיל את המאפיין bounds: bounds הוא אובייקט google.maps.LatLngBounds שמציין את האזור שבו יש לחפש מקומות. התוצאות מוטות, אבל לא רק, למקומות שנכללים בגבולות האלה.

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

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);
});

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);
});

להצגת דוגמה

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

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

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

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;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

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

רוצה לנסות דוגמה?

להצגת דוגמה

אסימוני סשן

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

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

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

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

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

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

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

מידע נוסף על אסימוני סשן

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

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

איור גרפי של מחלקות ה-CSS עבור הווידג&#39;טים של השלמה אוטומטית
      ושל 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, ב-Place SDK ל-Android בווידג'ט להשלמה אוטומטית או ב-Place SDK עבור iOS בקרה על השלמה אוטומטית של ממשק המשתמש
  • עליכם להבין את שדות הנתונים החיוניים להשלמה אוטומטית של מקומות,
  • השדות של הטיה לפי מיקום והגבלת מיקום הם אופציונליים, אבל עשויה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
  • מומלץ להשתמש בטיפול בשגיאות כדי לוודא שהאפליקציה תיפגע אם ה-API מחזיר שגיאה.
  • חשוב לוודא שהאפליקציה שלך תטופל אם לא נבחרה אפשרות בחירה, ומציעה למשתמשים אפשרות להמשיך.

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

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

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

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

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

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

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

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

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

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

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

  1. מזהה המקום מתוך התשובה להשלמה אוטומטית של מקום
  2. אסימון הסשן שבו נעשה שימוש בבקשה להשלמה אוטומטית של מקום
  3. הפרמטר fields מציין את השדות של נתוני המקום שדרושים לך

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

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

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

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

כן

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

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

לא

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

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

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

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

כדאי לשקול עיכוב של בקשות להשלמה אוטומטית
ניתן להשתמש באסטרטגיות כמו השהיה של בקשה להשלמה אוטומטית של מקום עד שהמשתמש יקליד את שלושת או ארבעת התווים הראשונים, כך שהאפליקציה תשלח פחות בקשות. לדוגמה, אם תבצעו בקשות להשלמה אוטומטית של מקום עבור כל תו אחרי שהמשתמש הקליד את התו השלישי, המשמעות היא שאם המשתמש מקליד שבעה תווים ולאחר מכן בוחר חיזוי שעבורו שלחתם בקשה אחת של API לקידוד גיאוגרפי, העלות הכוללת תהיה 0.01632$ (4 * 0.00283$ השלמה אוטומטית לכל בקשה + 0.005 $קידוד גיאוגרפי).1

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

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


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

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

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

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

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

מכסות

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

כללי מדיניות

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