עיצוב מפות חדש יתווסף בקרוב לפלטפורמה של מפות Google. העדכון הזה בסגנון המפה כולל לוח צבעים חדש שמוגדר כברירת מחדל ושיפורים בחוויית השימוש במפות ובנוחות השימוש. כל סגנונות המפה יעודכנו באופן אוטומטי במרץ 2025. אפשר לקרוא מידע נוסף על זמינות ועל האפשרות להצטרף בשלב מוקדם יותר במאמר בנושא סגנון מפה חדש לפלטפורמה של מפות Google.
בדף זה מתוארת הספרייה בצד הלקוח שזמינה ב-Maps JavaScript API. אם ברצונך לעבוד עם שירות האינטרנט של Places API בשרת שלך, עיין בלקוח Node.js לשירותי מפות Google. בדף שבקישור הזה מוצגים גם לקוח Java, לקוח Python ו-Go Client עבור שירותי מפות Google.
מבוא
ההשלמה האוטומטית היא תכונה של ספריית 'מקומות' ב-Maps JavaScript API. ניתן להשתמש בהשלמה אוטומטית כדי להציג לאפליקציות שלך את ההתנהגות של חיפוש מסוג 'מקדמה' בשדה החיפוש של מפות Google.
שירות ההשלמה האוטומטית יכול למצוא התאמה למילים מלאות ולמחרוזות משנה, וכן לזיהוי שמות של מקומות, כתובות וקודי פלוס. לכן האפליקציות יכולות לשלוח שאילתות בזמן שהמשתמש מקליד, כדי לספק חיזויים של מקומות בזמן אמת.
איך מתחילים
לפני השימוש בספריית המקומות ב-API JavaScript של מפות Google, תחילה יש לוודא ש-Places API מופעל ב-Google Cloud Console, באותו פרויקט שהגדרת עבור Maps JavaScript API.
לוחצים על הלחצן 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:
ה-API מציע שני סוגים של ווידג'טים להשלמה אוטומטית, שאותם ניתן להוסיף דרך המחלקות Autocomplete ו-SearchBox בהתאמה.
בנוסף, תוכלו להשתמש במחלקה AutocompleteService כדי לאחזר
תוצאות של השלמה אוטומטית באופן פרוגרמטי (עיינו בחומר העזר בנושא API של JavaScript במפות Google:
AutomaticService class).
לפניכם סיכום של הכיתות הזמינות:
Autocomplete מוסיף שדה להזנת טקסט לדף האינטרנט ועוקב אחרי ערכי התווים בשדה הזה. כשהמשתמש מזין טקסט, ההשלמה האוטומטית מחזירה חיזויים של מקומות בצורת רשימת בחירה נפתחת. כשהמשתמש בוחר מקום מהרשימה, המידע על המקום מוחזר לאובייקט ההשלמה האוטומטית והאפליקציה שלך יכולה לאחזר אותו. תוכלו למצוא פרטים נוספים בהמשך.
איור 1: השלמה אוטומטית של שדה טקסט ורשימת בחירהאיור 2: מילוי טופס של כתובת
SearchBox מוסיף שדה להזנת טקסט לדף האינטרנט, באופן דומה מאוד ל-Autocomplete. אלה ההבדלים:
ההבדל העיקרי הוא בתוצאות
שמופיעות ברשימת הבחירות. SearchBox מספק רשימה מורחבת של חיזויים, שיכולים לכלול מקומות (כפי שמוגדר על ידי Places API) וגם הצעות למונחי חיפוש. לדוגמה, אם המשתמש מזין 'פיצה בירושלים', רשימת הבחירה עשויה לכלול את הביטוי 'פיצה בתל אביב, ישראל' וגם את השמות של פיצריות שונות.
ב-SearchBox יש פחות אפשרויות מאשר
ב-Autocomplete להגבלת החיפוש. קודם כל, אפשר
להטות את החיפוש ל-LatLngBounds נתון. במקרה הזה אפשר
להגביל את החיפוש למדינה ספציפית ולסוגי מקומות ספציפיים, וכן להגדיר את הגבולות. אפשר לקרוא מידע נוסף
בהמשך.
איור 3: תיבת חיפוש מציגה מונחי חיפוש וחיזויים של מקומות.למידע נוסף
אפשר ליצור אובייקט AutocompleteService כדי לאחזר חיזויים באופן פרוגרמטי. אפשר להתקשר אל getPlacePredictions() כדי
לאחזר מקומות תואמים, או להתקשר למספר getQueryPredictions() כדי
לאחזר מקומות תואמים בנוסף למונחי חיפוש מוצעים.
הערה: האפליקציה AutocompleteService לא מוסיפה פקדים בממשק המשתמש.
במקום זאת, השיטות שלמעלה מחזירות מערך של אובייקטים של חיזוי. כל
אובייקט חיזוי מכיל את הטקסט של החיזוי, וגם מידע על
ההתאמה ופרטים על האופן שבו התוצאה תואמת לקלט של המשתמש.
תוכלו לקרוא פרטים נוספים בהמשך.
הוספת ווידג'ט של השלמה אוטומטית
הווידג'ט Autocomplete יוצר שדה להזנת טקסט בדף האינטרנט, מספק חיזויים של מקומות ברשימת בחירות בממשק המשתמש ומחזיר את פרטי המקומות בתגובה לבקשת getPlace(). כל ערך ברשימת הבחירה מתאים למקום אחד (כפי שמוגדר ב-Places API).
הבנאי Autocomplete לוקח שני ארגומנטים:
רכיב HTML input מסוג text. זה שדה הקלט שאחריו שירות ההשלמה האוטומטית יעקוב ויצרף את התוצאות שלו.
מערך נתונים fields שייכלל בתשובה Place Details ב-PlaceResult שנבחר על ידי המשתמש. אם המאפיין לא מוגדר או אם ['ALL'] מועבר, כל השדות הזמינים מוחזרים ומחויבים (לא מומלץ לעשות זאת עבור פריסות של סביבת הייצור). לרשימת השדות, יש לעיין ב-PlaceResult.
מערך של types שמציין סוג מפורש או אוסף סוג, כפי שמפורט בסוגים הנתמכים. אם לא מציינים סוג, כל הסוגים מוחזרים.
bounds הוא אובייקט google.maps.LatLngBounds שמציין את האזור שבו מחפשים מקומות. התוצאות מוטות למקומות שנכללים בגבולות האלה, אך לא רק.
strictBounds הוא boolean
שמציין אם ה-API חייב להחזיר רק את המקומות שנמצאים רק בתוך האזור שהוגדר על-ידי bounds הנתון. ה-API לא מחזיר תוצאות מחוץ לאזור הזה, גם אם הן תואמות לקלט של המשתמשים.
אפשר להשתמש ב-componentRestrictions כדי להגביל תוצאות לקבוצות ספציפיות. בשלב הזה אפשר להשתמש ב-componentRestrictions כדי לסנן לפי עד 5 מדינות. יש להעביר את המדינות כקוד מדינה בן שני תווים שתואם לתקן ISO 3166-1 Alpha-2. יש להעביר מספר מדינות כרשימה של קודי מדינות.
ניתן להשתמש ב-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);
יש לציין שדות נתונים כדי למנוע חיוב על מק"טים של נתוני מקומות שאין לך צורך בהם. צריך לכלול את המאפיין fields ב-AutocompleteOptions שמועברים למבנה הווידג'טים, כמו שמוצג בדוגמה הקודמת, או לקרוא ל-setFields() באובייקט Autocomplete קיים.
יש להגדיר את האפשרות strictBounds כדי להגביל את התוצאות לגבולות הנוכחיים, על סמך אזור התצוגה של המפה או גבולות מלבניים.
autocomplete.setOptions({ strictBounds: true });
הגבלת החיזויים למדינה ספציפית
ניתן להשתמש באפשרות componentRestrictions או לקרוא לפונקציה setComponentRestrictions() כדי להגביל את החיפוש של ההשלמה האוטומטית לקבוצה ספציפית של עד חמש מדינות.
ניתן להשתמש באפשרות types או לקרוא לפונקציה setTypes() כדי להגביל חיזויים לסוגי מקומות מסוימים. האילוץ הזה מציין סוג או אוסף של סוגי מקומות, כפי שמפורט בסוגי מקומות.
אם לא מגדירים מגבלה, מוחזרים כל הסוגים.
עבור הערך של האפשרות types או עבור הערך שמועבר אל setTypes(), אפשר לציין:
כשמשתמש בוחר מקום מהחיזויים המצורפים לשדה הטקסט של ההשלמה האוטומטית, השירות מפעיל אירוע place_changed. כדי לקבל את פרטי
המקום:
יוצרים handler של אירועים לאירוע place_changed, וקוראים ל-addListener()
באובייקט Autocomplete כדי להוסיף את ה-handler.
קוראים לפונקציה Autocomplete.getPlace() באובייקט Autocomplete כדי לאחזר את האובייקט PlaceResult. לאחר מכן אפשר להשתמש באובייקט כדי לקבל מידע נוסף על המקום שנבחר.
כברירת מחדל, כשמשתמש בוחר מקום, ההשלמה האוטומטית מחזירה את כל שדות הנתונים הזמינים לגבי המקום שנבחר ותחויב בהתאם.
משתמשים ב-Autocomplete.setFields()
כדי לציין אילו שדות של נתוני מקום להחזיר. מידע נוסף על האובייקט PlaceResult, כולל רשימת שדות של נתוני מקום שאפשר לבקש. כדי להימנע מתשלום על נתונים שאין בהם צורך, חשוב להשתמש ב-Autocomplete.setFields() כדי לציין
רק את נתוני המקום שבהם משתמשים.
במקרה של טופסי כתובת, מומלץ לקבל את הכתובת בפורמט מובנה. כדי
להחזיר את הכתובת המובנית של המקום שנבחר, מתקשרים אל
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();
}
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.
// 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);
});
// 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)
וגם מונחי חיפוש מוצעים. לדוגמה, אם המשתמש מזין 'פיצה בירושלים', רשימת הבחירה עשויה לכלול את הביטוי 'פיצה בתל אביב, ישראל' וגם את השמות של פיצריות שונות.
distance_meters הוא המרחק במטרים של המקום
מה-AutocompletionRequest.origin שצוין.
השדה matched_substrings מכיל קבוצה של מחרוזות משנה בתיאור
שתואמות לרכיבים בקלט של המשתמש. האפשרות הזו שימושית כדי להדגיש את מחרוזות המשנה האלה באפליקציה. במקרים רבים, השאילתה תופיע כמחרוזת משנה של שדה התיאור.
length הוא האורך של מחרוזת המשנה.
offset הוא היסט התווים, שנמדד מתחילת מחרוזת התיאור, שבה מופיעה מחרוזת המשנה התואמת.
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;
// 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;
<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 לווידג'טים של השלמה אוטומטית ותיבת חיפוש
רמת 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 כדי לקבל תמיכה
ומשוב שקשורים לספרייה.
נסה רכיבי אינטרנט. אפשר להשתמש ב
רכיב האינטרנט
של בוחר המקומות כדי להפעיל קלט טקסט שמאפשר למשתמשי קצה לחפש כתובת או מקום ספציפיים באמצעות השלמה אוטומטית.
איור 1: קלט טקסט לחיפוש כתובת או מקום ספציפיים באמצעות השלמה אוטומטית
אופטימיזציה של השלמה אוטומטית במקומות
בקטע הזה מתוארות שיטות מומלצות שיעזרו לך להפיק את המרב
משירות ההשלמה האוטומטית של מקומות.
חשוב להבין את שדות הנתונים החיוניים להשלמה אוטומטית של מקומות כבר מההתחלה.
השדות 'הטיות לפי מיקום' ו'הגבלת מיקום' הם אופציונליים, אבל עשויה
להיות להם השפעה משמעותית על הביצועים של ההשלמה האוטומטית.
שימוש בטיפול בשגיאות כדי לוודא שהאיכות של האפליקציה תפחת בהדרגה אם ה-API מחזיר שגיאה.
צריך לוודא שהאפליקציה מטפלת במצב שבו לא נבחרה אפשרות ושהיא מציעה למשתמשים
אפשרות להמשיך.
שיטות מומלצות לאופטימיזציית עלויות
אופטימיזציה בסיסית של עלויות
כדי לייעל את עלות השימוש בשירות השלמה אוטומטית של מקומות, יש להשתמש במסכות של שדות בווידג'טים של 'פרטי מקום' ו'השלמה אוטומטית של מקום' כדי להחזיר רק את השדות של נתוני המקום שנחוצים לכם.
אופטימיזציה מתקדמת של עלויות
כדאי להשתמש בהטמעה פרוגרמטית של השלמה אוטומטית של מקומות כדי לגשת לתמחור לפי בקשה ולבקש תוצאות של Geocoding API לגבי המקום שנבחר במקום 'פרטי מקום'. תמחור לפי בקשה בשילוב עם Geocoding API משתלם יותר מתמחור לכל סשן (מבוסס-ביקור) אם מתקיימים שני התנאים הבאים:
אם יש צורך רק בקווי הרוחב/האורך או הכתובת של המקום שנבחר על ידי המשתמש, ה-Geocoding API יספק את המידע הזה עבור פחות משיחה של 'פרטי מקום'.
אם משתמשים בוחרים בחיזוי להשלמה אוטומטית בתוך ארבע בקשות לחיזויים של ההשלמה האוטומטית בממוצע, או פחות, התמחור לפי בקשה עשוי להיות משתלם יותר מהתמחור לכל סשן.
כדי לקבל עזרה בבחירת ההטמעה של השלמה אוטומטית למקומות בהתאם לצרכים שלכם, צריך לבחור את הכרטיסייה של התשובה לשאלה הבאה.
האם הבקשה שלך דורשת מידע נוסף מלבד הכתובת וקו הרוחב/קו האורך של החיזוי שנבחר?
ההנחיות הבאות מתארות דרכים לביצוע אופטימיזציה של ביצועי ההשלמה האוטומטית של מקומות:
להוסיף הגבלות לפי מדינה,
הטיות לפי מיקום
והעדפות שפה (בהטמעות פרוגרמטיות) להטמעה של
ההשלמה האוטומטית של מקומות. בווידג'טים אין צורך
בהעדפת שפה, כי הם בוחרים את העדפות השפה מהדפדפן או מהנייד של המשתמש.
אם ההשלמה האוטומטית של מקום מלווה במפה, ניתן להטות את המיקום לפי אזור התצוגה של המפה.
במצבים שבהם המשתמש לא בוחר באחד מהחיזויים של ההשלמה האוטומטית, בדרך כלל
מאחר שאף אחד מהחיזויים האלה אינו כתובת של התוצאה הרצויה, אפשר להשתמש שוב בקלט המקורי של המשתמש כדי לנסות לקבל תוצאות רלוונטיות יותר:
אם אתם מצפים שהמשתמש יזין רק פרטי כתובת, השתמשו שוב בקלט המקורי של המשתמש בשיחה אל Geocoding API.
אם אתם מצפים שהמשתמש יזין שאילתות לגבי מקום ספציפי לפי שם או כתובת, השתמשו בבקשה לחיפוש מקום.
אם צפויות תוצאות רק באזור ספציפי, השתמשו
בתעדוף לפי מיקום.
תרחישים אחרים שבהם כדאי לחזור ל-Geocoding API כוללים:
משתמשים שמזינים כתובות של הנחות משנה במדינות שבהן התמיכה בהשלמה אוטומטית של מקומות
בכתובות של תת-דומיינים לא הושלמה, למשל צ'כיה, אסטוניה וליטא. לדוגמה, הכתובת בצ'כית "Stroupežnického 3191/17, Praha" מניבה חיזוי חלקי בהשלמה אוטומטית של מקום.
משתמשים שמזינים כתובות עם קידומות של קטעי כביש, כמו " 23-30 29th St, Queens" בניו יורק, או " 47-380 Kamehameha Hwy, Kaneohe" באי קאואי שבהוואי.
