השלמה אוטומטית של מקומות (חדש)

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

מפתחים באזור הכלכלי האירופי (EEA)

השירות Autocomplete (New) הוא API ל-iOS שמחזיר הצעות למקומות בתגובה לבקשה. בבקשה, מציינים מחרוזת לחיפוש טקסט וגבולות גיאוגרפיים שקובעים את אזור החיפוש.

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

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

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

הצעות המקומות שמוחזרות נועדו להצגה למשתמש כדי שהוא יוכל לבחור את המקום הרצוי. אפשר לשלוח בקשת Place Details (New) כדי לקבל מידע נוסף על כל אחת מההצעות למקומות שמוחזרות.

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

קבלת תחזיות לגבי מקומות באופן פרוגרמטי

בקשות להשלמה אוטומטית (חדש)

כדי ליצור בקשה להשלמה אוטומטית, קוראים ל-method ב-GMSPlacesClient. אפשר להעביר פרמטרים באובייקט GMSAutocompleteRequest. התשובה מספקת הצעות להשלמה אוטומטית באובייקט GMSAutocompletePlaceSuggestion.

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

גרסת Places Swift SDK

כדי ליצור בקשה להשלמה אוטומטית, קוראים ל-method ב-PlacesClient. אפשר להעביר פרמטרים באובייקט AutocompleteRequest. התשובה מספקת הצעות להשלמה אוטומטית באובייקט AutocompletePlaceSuggestion.

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

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

Places Swift SDK

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

Swift

let token = GMSAutocompleteSessionToken()

let northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051)
let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds)

let request = GMSAutocompleteRequest(query:"Spagh")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

תשובות להשלמה אוטומטית (חדש)

ההשלמה האוטומטית מחזירה מערך של עד חמישה מקרים של GMSAutocompleteSuggestion. המערך מכיל:

  • placeID
  • types: סוגים שרלוונטיים למקום הזה.
  • distanceMeters: המרחק מנקודת המוצא.
  • attributedFullText: הטקסט המלא של ההצעה, שקריא לאנשים.
  • attributedPrimaryText: הטקסט הראשי של ההצעה שקריא לאנשים.
  • attributedSecondaryText: טקסט משני של הצעה שקריא לאנשים.
  • structuredFormat: השם הספציפי והטקסט שמבחין בין השמות, כמו עיר או אזור.

פרמטרים נדרשים

שאילתה

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

פרמטרים אופציונליים

sessionToken

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

אפשר לחשוף את טוקן הסשן של השלמה אוטומטית של מקומות כדי להעביר אותו לשירותים אחרים שלא נכללים ב-Places SDK ל-iOS, כמו אימות כתובות:

Places Swift SDK

let token = AutocompleteSessionToken()
let filter = AutocompleteFilter(origin: CLLocationCoordinate2DMake(39.7, -94.5))
let request = AutocompleteRequest(query: "Piz", sessionToken: token, filter: filter)

PlacesClient.shared.fetchAutocompleteSuggestions(request: request) {
    case .success(let suggestions):
      ...
    case .failure(let placesError):
      print(placesError) 
}

// pass token's string format to use with a service that is not a part of iOS SDK.
print("token: \(token)")

Objective-C

GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Piz"];
GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init];
request.sessionToken = token;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:39.7 longitude:-94.5];
filter.locationBias = GMSPlaceRectangularLocationOption(topLocation, bottomLocation);

request.filter = filter;
 [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request
                     callback:^(NSArray<GMSAutocompleteSuggestion *> *_Nullable results,
                                NSError *_Nullable error) {
  ...
}];

// pass token's string format to use with a service that is not a part of iOS SDK.
NSLog(@"%@", token.description);

מידע נוסף זמין במאמר בנושא אסימוני סשן.

פרמטרים אופציונליים של AutocompleteFilter

סוגים

אפשר לשייך למקום רק סוג ראשי אחד מתוך הסוגים טבלה א' או טבלה ב'. לדוגמה, הסוג הראשי יכול להיות mexican_restaurant או steak_house.

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

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

הבקשה נדחית עם השגיאה INVALID_REQUEST אם:

  • צוינו יותר מחמישה סוגים.
  • מצוינים סוגים לא מזוהים.

לדוגמה, כדי להגביל את התוצאות לחנויות לציוד ספורט, מציינים את הסוג הזה ב-AutocompleteFilter:

Places Swift SDK

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
  

Swift

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
  

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];

ארצות

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

Places Swift SDK

let filter = AutocompleteFilter(countries: ["DE", "FR"])
  

Swift

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

אם מציינים גם locationRestriction וגם countries, התוצאות יהיו באזור החיתוך של שתי ההגדרות.

inputOffset

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

locationBias או locationRestriction

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

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

  • השדה locationRestriction מציין אזור לחיפוש. לא מוחזרות תוצאות מחוץ לאזור שצוין.

מציינים את האזור locationBias או locationRestriction כחלון תצוגה מלבני או כעיגול.

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

לדוגמה:

Places Swift SDK

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

Swift

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

מלבן הוא אזור תצוגה של קווי רוחב ואורך, שמיוצג על ידי שתי נקודות low ו-high שממוקמות באלכסון אחת מול השנייה. אזור התצוגה נחשב לאזור סגור, כלומר הוא כולל את הגבול שלו. הגבולות של קו הרוחב צריכים להיות בין 90- ל-90 מעלות, כולל, והגבולות של קו האורך צריכים להיות בין 180- ל-180 מעלות, כולל:

  • אם low = high, אזור התצוגה מורכב מהנקודה היחידה הזו.
  • אם low.longitude > high.longitude, טווח קווי האורך הפוך (אזור התצוגה חוצה את קו האורך 180 מעלות).
  • אם low.longitude = ‎-180 degrees ו-high.longitude= 180 degrees, אז אזור התצוגה כולל את כל קווי האורך.
  • אם low.longitude = 180 מעלות ו-high.longitude = ‎-180 מעלות, טווח קווי האורך ריק.

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

לדוגמה, אזור התצוגה הזה כולל את כל העיר ניו יורק:

Places Swift SDK

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

Swift

let high = CLLocationCoordinate2DMake(40.921628, -73.700051)
let low = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

Objective-C

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

origin

נקודת המוצא שממנה יחושב המרחק בקו ישר ליעד (הערך שמוחזר כ-distanceMeters). אם לא מציינים את הערך הזה, המרחק בקו ישר לא יוחזר. חובה לציין את הקואורדינטות של קו הרוחב וקו האורך:

Places Swift SDK

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
  

Swift

let filter = GMSAutocompleteFilter()
filter.origin =  CLLocation(latitude: 37.395804, longitude: -122.077023)
 

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];

regionCode

קוד האזור שמשמש לעיצוב התגובה, שמוגדר כערך ccTLD (דומיין ברמה העליונה) באורך שני תווים. רוב קודי ה-ccTLD זהים לקודי ISO 3166-1, אבל יש כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), והקוד שלה לפי ISO 3166-1 הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד').

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

shouldIncludePureServiceAreaBusinesses

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

לדוגמה:

Places Swift SDK

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Swift

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.shouldIncludePureServiceAreaBusinesses = YES;

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

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

ווידג&#39;ט ההשלמה האוטומטית למקומות

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

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

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

פרמטרים של הווידג'ט Place Autocomplete

בנוסף לפרמטרים שזמינים באופן פרוגרמטי, הווידג'ט Place Autocomplete מציע גם את הפרמטרים הבאים.

הצג

show מציין אם הווידג'ט מוצג.

onSelection

הסגירה שתופעל כשבוחרים מקום.

onError

הסגירה שמופעלת כשמתרחשת שגיאה. אם מתרחשת שגיאה, המערכת תעביר את הערך A PlacesError.

התאמה אישית של התוכן והעיצוב

הפרמטרים של AutocompleteUICustomization מציינים את ההתאמות האישיות של ממשק המשתמש שיוחלו על הווידג'ט. אפשרויות ההתאמה האישית הן:

  • AutocompleteListDensity. הפרמטר הזה מאפשר לכם לבחור את הצפיפות של רשימת ההצעות, multiLine או twoLine.
  • AutocompleteUIIcon. הפרמטר הזה מאפשר לכם לבחור אם להציג את סמל ברירת המחדל לכל פריט ברשימה.
  • theme. הפרמטר הזה מציין עיצוב מותאם אישית שמבטל את כל מאפייני הסגנון שמוגדרים כברירת מחדל. אתם יכולים להתאים אישית את הצבעים, הטיפוגרפיה, הריווח, הגבולות והפינות של רכיב ההשלמה האוטומטית של מקומות. ערך ברירת המחדל הוא PlacesMaterialTheme. מאפייני עיצוב שלא מוגדרים מחדש משתמשים בסגנונות ברירת המחדל.

דוגמה מלאה של קוד

דוגמאות להשלמה אוטומטית (חדש)

שימוש בפרמטרים locationRestriction ו-locationBias

ההשלמה האוטומטית (חדש) משתמשת בהטיה לפי כתובת IP כברירת מחדל כדי לשלוט באזור החיפוש. בשיטת ההטיה לפי כתובת IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות. אפשר להשתמש ב-locationRestriction או ב-locationBias, אבל לא בשניהם, כדי לציין אזור לחיפוש.

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

Places Swift SDK

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Swift

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius)

let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

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

Places Swift SDK

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Swift

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

let request = GMSAutocompleteRequest(query:"Piz")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

סוגי שימושים

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

בדוגמה הבאה מצוין מחרוזת שאילתה של 'כדורגל' ונעשה שימוש בפרמטר types כדי להגביל את התוצאות למקומות מסוג "sporting_goods_store":

Places Swift SDK

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
    

Swift

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]

let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

שימוש במקור

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

בדוגמה הזו, המקור מוגדר למרכז סן פרנסיסקו:

Places Swift SDK

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Swift

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin

let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))")
        }
      }
    })

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

התאמה אישית של התוכן והעיצוב

Swift

let uiCustomization = AutocompleteUICustomization(
    listDensity: .multiLine,
    listItemIcon: .noIcon,
    theme: PlacesMaterialTheme()
)

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

Places Swift SDK

struct PlaceAutocompleteDemoView: View {

  @State private var fetchedPlace: Place?
  @State private var placesError: PlacesError?
  @State private var showWidget = false

  public var body: some View {
    VStack {
      Button("Search for a place") {
        showWidget.toggle()
      }
      .placeAutocomplete(
        show: $showWidget,
        onSelection: { (autocompletePlaceSuggestion, autocompleteSessionToken) in
          Task {
            let placesClient = await PlacesClient.shared
            let fetchPlaceRequest = FetchPlaceRequest(
              placeID: autocompletePlaceSuggestion.placeID,
              placeProperties: [.displayName, .formattedAddress],
              sessionToken: autocompleteSessionToken
            )

            switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
            case .success(let place):
              print("Fetched place: \(place)")
              self.fetchedPlace = place
            case .failure(let placesError):
              print("Failed to fetch place: \(placesError)")
              self.placesError = placesError
            }
          }
        },
        onError: { placesError in
          self.placesError = placesError
        }
      )
    }
  }
}

אופטימיזציה של השלמה אוטומטית (חדש)

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

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

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

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

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

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

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

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

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

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

כן, צריך עוד פרטים

שימוש בהשלמה אוטומטית מבוססת-סשן (חדש) עם Place Details (חדש).
מכיוון שהאפליקציה שלך דורשת פרטים על מקומות (חדש), כמו שם המקום, סטטוס העסק או שעות הפתיחה, ההטמעה של ההשלמה האוטומטית (חדש) צריכה להשתמש באסימון סשן (באופן פרוגרמטי או מוטמע בווידג'טים של JavaScript,‏ Android או iOS) לכל סשן, בנוסף למק"טים הרלוונטיים של Places, בהתאם לשדות הנתונים של המקום שביקשת.1

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

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

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

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

יכול להיות ש-Geocoding API יהיה אפשרות חסכונית יותר מאשר Place Details (New) לאפליקציה שלכם, בהתאם לביצועים של השימוש ב-Autocomplete (New). היעילות של ההשלמה האוטומטית (חדשה) בכל אפליקציה משתנה בהתאם למה שהמשתמשים מזינים, איפה האפליקציה נמצאת והאם הוטמעו שיטות מומלצות לאופטימיזציה של הביצועים.

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

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

כן

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

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

לא

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

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

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

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

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

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

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


  1. למידע על עלויות, אפשר לעיין ברשימות המחירים של הפלטפורמה של מפות Google.

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

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

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

הטיה של מיקום

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

הגבלת מיקום

כדי להגביל את התוצאות לאזור מסוים, מעבירים פרמטר locationRestriction.

אפשר גם להגביל את התוצאות לאזור שהוגדר על ידי location והפרמטר radius, על ידי הוספת הפרמטר locationRestriction. ההוראה הזו גורמת להשלמה האוטומטית (חדשה) להחזיר רק תוצאות באזור הזה.