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

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

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

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

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

מבוא

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

תחילת העבודה

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

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

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

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

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

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

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

סיכום של הכיתות

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

סיכום של הכיתות הזמינות:

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

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

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

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

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

הווידג'ט Autocomplete יוצר שדה קלט טקסט בדף האינטרנט שלכם, מספק חיזויים של מקומות ברשימת בחירת ממשק המשתמש ומחזיר פרטי מקומות בתגובה לבקשת getPlace(). כל ערך ברשימת הבחירה תואם למקום אחד (כפי שמוגדר בממשק ה-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. ניתן להשתמש במזהה המקום המוחזר עם הקריאות לשירותים 'מקומות', קידוד גיאוגרפי, מסלולים או מטריצת מרחק.
  הערה: המאפיין 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,
  types: ["establishment"],
};

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,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

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

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

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

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

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

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

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

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

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

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

TypeScript

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

autocomplete.setBounds(newBounds);index.ts

JavaScript

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

autocomplete.setBounds(newBounds);
index.js

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

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

TypeScript

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

JavaScript

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

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

TypeScript

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

JavaScript

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

דוגמה

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

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

autocomplete.setOptions({ strictBounds: true });

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

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

TypeScript

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

JavaScript

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

דוגמה

אילוץ סוגי מקומות

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

אפשר להזין כאן את הערכים הבאים: לערך של types או ל-setTypes():

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

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

או:

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

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

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

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

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

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

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

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

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

כתובת_רחוב
שטח
מוסד

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

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

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

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

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

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

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

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

רכיב HTML input מסוג 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);
});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

דוגמה

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

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

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

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

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

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

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>
    <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
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>index.html

לדגום

Stackblitch.com CodeSandbox.io JSFiddle.net GitPod.io Google Cloud Shell

דוגמה

אסימוני סשנים

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

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

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

מידע נוסף על אסימוני סשנים.

עיצוב הווידג'טים של השלמה אוטומטית ו-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`.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כן

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

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

לא

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

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

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

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

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

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

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

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

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

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

מכסות

למידע על מכסות ותמחור, אפשר לקרוא את מסמכי התיעוד לשימוש ולחיוב ב-Places API.

מדיניות

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

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

מבוא

תחילת העבודה

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

סיכום של הכיתות

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

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

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

TypeScript

JavaScript

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

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

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

TypeScript

JavaScript

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

TypeScript

JavaScript

TypeScript

JavaScript

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

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

TypeScript

JavaScript

אילוץ סוגי מקומות

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

TypeScript

JavaScript

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

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

שינוי אזור החיפוש עבור SearchBox

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

TypeScript

JavaScript

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

TypeScript

JavaScript

CSS

HTML

לדגום

אסימוני סשנים

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

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

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

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

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

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

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

כן

לא

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

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

מכסות

מדיניות