מבוא
ההשלמה האוטומטית היא תכונה של ספריית 'מקומות' ב-Maps JavaScript API. ניתן להשתמש בהשלמה אוטומטית כדי להציג לאפליקציות שלך את ההתנהגות של חיפוש מסוג 'מקדמה' בשדה החיפוש של מפות Google. שירות ההשלמה האוטומטית יכול למצוא התאמה למילים מלאות ולמחרוזות משנה, וכן לזיהוי שמות של מקומות, כתובות וקודי פלוס. לכן האפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקליד, כדי לספק חיזויים של מקומות בזמן אמת. כפי שמוגדר על ידי Places API, 'מקום' יכול להיות מוסד, מיקום גיאוגרפי או נקודת עניין בולטת.
איך מתחילים
לפני השימוש בספריית המקומות ב-API JavaScript של מפות Google, תחילה יש לוודא ש-Places API מופעל ב-Google Cloud Console, באותו פרויקט שהגדרת עבור Maps JavaScript API.
כדי לראות את הרשימה של ממשקי ה-API שמופעלים:
- נכנסים אל מסוף Google Cloud.
- לוחצים על הלחצן Select a project, בוחרים את הפרויקט שהגדרתם עבור Maps JavaScript API ולוחצים על Open.
- ברשימת ממשקי ה-API במרכז הבקרה, מחפשים את Places API.
- אם ה-API מופיע ברשימה, אז לא צריך לבצע פעולה נוספת. אם ממשק ה-API לא מופיע ברשימה,
מפעילים אותו:
- בחלק העליון של הדף, לוחצים על ENABLE API כדי להציג את הכרטיסייה Library. לחלופין, בתפריט הימני לוחצים על ספרייה.
- מחפשים את Places API ובוחרים אותו מרשימת התוצאות.
- בוחרים באפשרות הפעלה. בסיום התהליך, יופיע Places API ברשימת ממשקי ה-API במרכז הבקרה.
הספרייה בטעינה
שירות 'מקומות' הוא ספרייה עצמאית, הנפרדת מקוד ה-API הראשי של JavaScript במפות. כדי להשתמש בפונקציונליות שכלולה
בספרייה הזו, קודם צריך לטעון אותה באמצעות הפרמטר 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
כדי לאחזר
תוצאות של השלמה אוטומטית באופן פרוגרמטי (עיינו בחומר העזר בנושא API של JavaScript במפות Google:
AutomaticService class).
לפניכם סיכום של הכיתות הזמינות:
-
Autocomplete
מוסיף שדה להזנת טקסט לדף האינטרנט ועוקב אחרי ערכי התווים בשדה הזה. כשהמשתמש מזין טקסט, ההשלמה האוטומטית מחזירה חיזויים של מקומות בצורת רשימת בחירה נפתחת. כשהמשתמש בוחר מקום מהרשימה, המידע על המקום מוחזר לאובייקט ההשלמה האוטומטית והאפליקציה שלך יכולה לאחזר אותו. תוכלו למצוא פרטים נוספים בהמשך. -
SearchBox
מוסיף שדה להזנת טקסט לדף האינטרנט, באופן דומה מאוד ל-Autocomplete
. אלה ההבדלים:- ההבדל העיקרי הוא בתוצאות
שמופיעות ברשימת הבחירות.
SearchBox
מספק רשימה מורחבת של חיזויים, שיכולים לכלול מקומות (כפי שמוגדר על ידי Places API) וגם הצעות למונחי חיפוש. לדוגמה, אם המשתמש מזין 'פיצה בירושלים', רשימת הבחירה עשויה לכלול את הביטוי 'פיצה בתל אביב, ישראל' וגם את השמות של פיצריות שונות. - ב-
SearchBox
יש פחות אפשרויות מאשר ב-Autocomplete
להגבלת החיפוש. קודם כל, אפשר להטות את החיפוש ל-LatLngBounds
נתון. במקרה הזה אפשר להגביל את החיפוש למדינה ספציפית ולסוגי מקומות ספציפיים, וכן להגדיר את הגבולות. אפשר לקרוא מידע נוסף בהמשך.
- ההבדל העיקרי הוא בתוצאות
שמופיעות ברשימת הבחירות.
- אפשר ליצור אובייקט
AutocompleteService
כדי לאחזר חיזויים באופן פרוגרמטי. אפשר להתקשר אלgetPlacePredictions()
כדי לאחזר מקומות תואמים, או להתקשר למספרgetQueryPredictions()
כדי לאחזר מקומות תואמים בנוסף למונחי חיפוש מוצעים. הערה: האפליקציהAutocompleteService
לא מוסיפה פקדים בממשק המשתמש. במקום זאת, השיטות שלמעלה מחזירות מערך של אובייקטים של חיזוי. כל אובייקט חיזוי מכיל את הטקסט של החיזוי, וגם מידע על ההתאמה ופרטים על האופן שבו התוצאה תואמת לקלט של המשתמש. תוכלו לקרוא פרטים נוספים בהמשך.
הוספת ווידג'ט של השלמה אוטומטית
הווידג'ט Autocomplete
יוצר שדה להזנת טקסט בדף האינטרנט, מספק חיזויים של מקומות ברשימת בחירות בממשק המשתמש ומחזיר את פרטי המקומות בתגובה לבקשת getPlace()
. כל ערך ברשימת הבחירה מתאים למקום אחד (כפי שמוגדר ב-Places API).
הבנאי Autocomplete
לוקח שני ארגומנטים:
- רכיב HTML
input
מסוגtext
. זה שדה הקלט שאחריו שירות ההשלמה האוטומטית יעקוב ויצרף את התוצאות שלו. - ארגומנט אופציונלי של
AutocompleteOptions
, שיכול להכיל את המאפיינים הבאים:- מערך נתונים
fields
שייכלל בתשובהPlace Details
ב-PlaceResult
שנבחר על ידי המשתמש. אם המאפיין לא מוגדר או אם['ALL']
מועבר, כל השדות הזמינים מוחזרים ומחויבים (לא מומלץ לעשות זאת עבור פריסות של סביבת הייצור). לרשימת השדות, יש לעיין ב-PlaceResult
. - מערך של
types
שמציין סוג מפורש או אוסף סוג, כפי שמפורט בסוגים הנתמכים. אם לא מציינים סוג, כל הסוגים מוחזרים. bounds
הוא אובייקטgoogle.maps.LatLngBounds
שמציין את האזור שבו מחפשים מקומות. התוצאות מוטות למקומות שנכללים בגבולות האלה, אך לא רק.strictBounds
הואboolean
שמציין אם ה-API חייב להחזיר רק את המקומות שנמצאים רק בתוך האזור שהוגדר על-ידיbounds
הנתון. ה-API לא מחזיר תוצאות מחוץ לאזור הזה, גם אם הן תואמות לקלט של המשתמשים.- אפשר להשתמש ב-
componentRestrictions
כדי להגביל תוצאות לקבוצות ספציפיות. בשלב הזה אפשר להשתמש ב-componentRestrictions
כדי לסנן לפי עד 5 מדינות. יש להעביר את המדינות כקוד מדינה בן שני תווים שתואם לתקן ISO 3166-1 Alpha-2. יש להעביר מספר מדינות כרשימה של קודי מדינות.הערה: אם מתקבלות תוצאות לא צפויות עם קוד מדינה, ודאו שאתם משתמשים בקוד שכולל את המדינות, הטריטוריות התלויות והאזורים הגיאוגרפיים המיוחדים שהתכוונתם אליהם. מידע על קודים זמין במאמר ויקיפדיה: רשימת קודי מדינות בתקן ISO 3166 או פלטפורמת הגלישה באינטרנט של ISO.
- ניתן להשתמש ב-
placeIdOnly
כדי להורות לווידג'טAutocomplete
לאחזר רק מזהי מקומות. בקריאה ל-getPlace()
באובייקטAutocomplete
, ב-PlaceResult
שהופכים להיות זמינים יוגדרו רק המאפייניםplace id
,types
ו-name
. אפשר להשתמש במזהה המקום שמוחזר בשיחות לשירותים 'מקומות', 'קידוד גיאוגרפי', 'מסלול' או 'מטריצת מרחק'.
- מערך נתונים
הגבלת חיזויים של השלמה אוטומטית
כברירת מחדל, ההשלמה האוטומטית של מקום מציגה את כל סוגי המקומות, ללא חיזוי לחיזויים שנמצאים בקרבת המיקום של המשתמש, ומאחזרת את כל שדות הנתונים הזמינים לגבי המקום שהמשתמש בוחר. הגדירו אפשרויות להשלמה אוטומטית של מקומות כדי להציג חיזויים רלוונטיים יותר על סמך התרחיש לדוגמה שלכם.
הגדרת אפשרויות בזמן הבנייה
ה-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 מסוגי מקומות. למשל:
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()
כדי לציין
רק את נתוני המקום שבהם משתמשים.
המאפיין 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
לוקח שני ארגומנטים:
- רכיב 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); });
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> <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>
רוצה לנסות את הדוגמה
אסימוני סשן
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 | תיאור |
---|---|
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 . |
שימוש ברכיב של בורר המקומות
הערה: הדוגמה הזו משתמשת בספריית קוד פתוח. אפשר לעיין בקובץ README כדי לקבל תמיכה ומשוב שקשורים לספרייה.
נסה רכיבי אינטרנט. אפשר להשתמש ב רכיב האינטרנט של בוחר המקומות כדי להפעיל קלט טקסט שמאפשר למשתמשי קצה לחפש כתובת או מקום ספציפיים באמצעות השלמה אוטומטית.
אופטימיזציה של השלמה אוטומטית במקומות
בקטע הזה מתוארות שיטות מומלצות שיעזרו לך להפיק את המרב משירות ההשלמה האוטומטית של מקומות.
הנה כמה הנחיות כלליות:
- הדרך המהירה ביותר לפתח ממשק משתמש פעיל היא להשתמש בווידג'ט להשלמה אוטומטית של API של מפות Google, ב-Place SDK ל-Android ווידג'ט של השלמה אוטומטית או ב-Place SDK ל-iOS, בקרה על השלמה אוטומטית של ממשק משתמש
- חשוב להבין את שדות הנתונים החיוניים להשלמה אוטומטית של מקומות כבר מההתחלה.
- השדות 'הטיות לפי מיקום' ו'הגבלת מיקום' הם אופציונליים, אבל עשויה להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
- שימוש בטיפול בשגיאות כדי לוודא שהאיכות של האפליקציה תפחת בהדרגה אם ה-API מחזיר שגיאה.
- צריך לוודא שהאפליקציה מטפלת במצב שבו לא נבחרה אפשרות ושהיא מציעה למשתמשים אפשרות להמשיך.
שיטות מומלצות לאופטימיזציית עלויות
אופטימיזציה בסיסית של עלויות
כדי לייעל את עלות השימוש בשירות השלמה אוטומטית של מקומות, יש להשתמש במסכות של שדות בווידג'טים של 'פרטי מקום' ו'השלמה אוטומטית של מקום' כדי להחזיר רק את השדות של נתוני המקום שנחוצים לכם.
אופטימיזציה מתקדמת של עלויות
כדאי להשתמש בהטמעה פרוגרמטית של השלמה אוטומטית של מקומות כדי לגשת לתמחור לפי בקשה ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום 'פרטי מקום'. תמחור לפי בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לכל סשן (מבוסס-ביקור) אם מתקיימים שני התנאים הבאים:
- אם יש צורך רק בקווי הרוחב/האורך או הכתובת של המקום שנבחר על ידי המשתמש, ה-Geocoding API יספק את המידע הזה עבור פחות משיחה של 'פרטי מקום'.
- אם משתמשים בוחרים בחיזוי להשלמה אוטומטית בתוך ארבע בקשות לחיזויים של ההשלמה האוטומטית בממוצע, או פחות, התמחור לפי בקשה עשוי להיות משתלם יותר מהתמחור לכל סשן.
האם הבקשה שלך דורשת מידע נוסף מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?
כן, נדרשים פרטים נוספים
השתמשו בהשלמה אוטומטית של מקומות על בסיס פרטי המקום, עם פרטי המקום.
מאחר שהאפליקציה שלך דורשת פרטי מקום כמו שם המקום, סטטוס העסק או שעות הפתיחה, עליך להטמיע את ההשלמה האוטומטית של מקום באמצעות אסימון סשן (פרוגרמטי או מובנה בווידג'טים של JavaScript, Android או iOS) כך שהעלות הכוללת תהיה 0.017 $לכל סשן וגם מק"טים של נתוני המקומות הרלוונטיים, בהתאם לשדות המק"טים של נתוני המקומות בהתאם לשדות הבקשה המבוקשים.
הטמעת ווידג'ט
ניהול הסשנים מובנה באופן אוטומטי בווידג'טים JavaScript, Android או iOS. החיזוי הזה כולל גם את הבקשות להשלמה אוטומטית של מקומות וגם את הבקשה לפרטי מקום בחיזוי שנבחר. חשוב לציין את הפרמטר fields
כדי לוודא שביקשת רק את
השדות של נתוני המקום הדרושים.
הטמעה פרוגרמטית
יש להשתמש באסימון סשן עם הבקשות להשלמה אוטומטית של מקומות. כשמבקשים לקבל פרטי מקום לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מהתשובה להשלמה אוטומטית של מקום
- אסימון הסשן שבו נעשה שימוש בבקשת ההשלמה האוטומטית של מקום
- הפרמטר
fields
שמציין את השדות של נתוני המקום הדרושים
לא, צריך רק כתובת ומיקום
הממשק Geocoding API יכול להיות יותר חסכוני יותר מאשר 'פרטי מקום' עבור האפליקציה, בהתאם לביצועים של השימוש בהשלמה האוטומטית של מקומות. יעילות ההשלמה האוטומטית של כל אפליקציה משתנה בהתאם למה שהמשתמשים מזינים, למיקום שבו נעשה שימוש באפליקציה ולשאלה אם יושמו שיטות מומלצות לאופטימיזציית ביצועים.
כדי לענות על השאלה הבאה, צריך לנתח את מספר התווים הממוצע שמשתמש מקליד לפני שבוחרים חיזוי להשלמה אוטומטית של מקום באפליקציה.
האם המשתמשים שלכם בוחרים חיזוי להשלמה אוטומטית של מקומות בארבע בקשות או פחות, בממוצע?
כן
יש להטמיע באופן פרוגרמטי השלמה אוטומטית של מקומות ללא אסימוני סשן וקריאה ל-Geocoding API בחיזוי המקום שנבחר.
API לקידוד גיאוגרפי מספק כתובות וקואורדינטות של קווי אורך ורוחב בעלות של 0.005 $לבקשה. ביצוע ארבע בקשות מסוג השלמה אוטומטית במקום – לכל בקשה עולה 0.01,32$, כך שהעלות הכוללת של ארבע בקשות בתוספת קריאה ל-Geocoding API לגבי חיזוי המקום שנבחר תהיה 0.01632$, שהוא נמוך מהמחיר להשלמה אוטומטית לכל סשן בסך 0.017 $לכל סשן.1
נסו להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את התחזית שהם מחפשים, תוך שימוש בפחות תווים.
לא
השתמשו בהשלמה אוטומטית של מקומות על בסיס פרטי המקום, עם פרטי המקום.
מכיוון שהמספר הממוצע של הבקשות שאתם מצפים לשלוח לפני שמשתמש בוחר בחיזוי של השלמה אוטומטית של מקום, גבוה מהמחיר של כל סשן, אם תטמיעו את התכונה 'השלמה אוטומטית של מקומות', תצטרכו להשתמש באסימון סשן גם לבקשות להשלמה אוטומטית של מקומות וגם לבקשה של פרטי מקום שמשויכת, בעלות כוללת של 0.017 $לכל סשן.1
הטמעת ווידג'ט
ניהול הסשנים מובנה באופן אוטומטי בווידג'טים JavaScript, Android או iOS. החיזוי הזה כולל גם את הבקשות להשלמה אוטומטית של מקומות וגם את הבקשה לפרטי מקום בחיזוי שנבחר. חשוב לציין את הפרמטר fields
כדי לוודא שביקשת רק את השדות של נתונים בסיסיים.
הטמעה פרוגרמטית
יש להשתמש באסימון סשן עם הבקשות להשלמה אוטומטית של מקומות. כשמבקשים לקבל פרטי מקום לגבי החיזוי שנבחר, צריך לכלול את הפרמטרים הבאים:
- מזהה המקום מהתשובה להשלמה אוטומטית של מקום
- אסימון הסשן שבו נעשה שימוש בבקשת ההשלמה האוטומטית של מקום
- הפרמטר
fields
שבו מצוינים שדות נתונים בסיסיים, כמו כתובת וגיאומטריה
כדאי לשקול לעכב בקשות להשלמה אוטומטית של מקומות
ניתן להשתמש באסטרטגיות כמו השהיית בקשה להשלמה אוטומטית של מקום עד שהמשתמש יקליד בשלושת או ארבעת התווים הראשונים, כדי שהאפליקציה תשלח פחות בקשות. לדוגמה, שליחת בקשות להשלמה אוטומטית של מקומות עבור כל תו אחרי שהמשתמש הקליד את התו השלישי, המשמעות היא שאם המשתמש מקליד שבעה תווים ולאחר מכן בוחר חיזוי שעבורו אתם שולחים בקשה אחת ל-Geocoding API, העלות הכוללת תהיה 0.01632$ (4 * $0.00283 השלמה אוטומטית לכל בקשה + 0.005 $קידוד גיאוגרפי).1
אם מספר הבקשות הפרוגרמטי הממוצע שתוכלו לקבל נמוך מ-4, תוכלו לפעול לפי ההנחיות בנושא הטמעת השלמה אוטומטית של מקומות לפי ביצועים באמצעות Geocoding API. הערה: משתמשים שצפויים לצפות לראות חיזויים בכל הקשה חדשה על ידי הקשה על המקשים האלה, עלולים להיחשב כזמן אחזור אצל המשתמשים.
נסו להשתמש בשיטות מומלצות לשיפור הביצועים כדי לעזור למשתמשים לקבל את התחזית שהם מחפשים, בפחות תווים.
-
העלויות המפורטות כאן הן בדולר ארה"ב. לקבלת מידע על התמחור המלא, אפשר לעיין בדף חיוב בפלטפורמה של מפות Google.
שיטות מומלצות לשיפור הביצועים
ההנחיות הבאות מתארות דרכים לביצוע אופטימיזציה של ביצועי ההשלמה האוטומטית של מקומות:
- להוסיף הגבלות לפי מדינה, הטיות לפי מיקום והעדפות שפה (בהטמעות פרוגרמטיות) להטמעה של ההשלמה האוטומטית של מקומות. בווידג'טים אין צורך בהעדפת שפה, כי הם בוחרים את העדפות השפה מהדפדפן או מהנייד של המשתמש.
- אם ההשלמה האוטומטית של מקום מלווה במפה, ניתן להטות את המיקום לפי אזור התצוגה של המפה.
- במצבים שבהם המשתמש לא בוחר באחד מהחיזויים של ההשלמה האוטומטית, בדרך כלל
מאחר שאף אחד מהחיזויים האלה אינו כתובת של התוצאה הרצויה, אפשר להשתמש שוב בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
- אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, השתמשו שוב בקלט המקורי של המשתמש בשיחה אל Geocoding API.
- אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, השתמשו בבקשה לחיפוש מקום. אם צפויות תוצאות רק באזור ספציפי, השתמשו בתעדוף לפי מיקום.
- משתמשים שמזינים כתובות של הנחות משנה במדינות שבהן התמיכה בהשלמה אוטומטית של מקומות בכתובות של תת-דומיינים לא הושלמה, למשל צ'כיה, אסטוניה וליטא. לדוגמה, הכתובת בצ'כית "Stroupežnického 3191/17, Praha" מניבה חיזוי חלקי בהשלמה אוטומטית של מקום.
- משתמשים שמזינים כתובות עם קידומות של קטעי כביש, כמו " 23-30 29th St, Queens" בניו יורק, או " 47-380 Kamehameha Hwy, Kaneohe" באי קאואי שבהוואי.
מגבלות שימוש ומדיניות
מכסות
למידע על מכסות ותמחור, ראו את משאבי העזרה בנושא שימוש וחיוב של Places API.
כללי מדיניות
השימוש בספריית המקומות, API של JavaScript במפות Google חייב להיות בהתאם למדיניות שמתוארת עבור Places API.