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

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

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

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

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

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

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

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

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

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

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

כדי ליצור בקשה להשלמה אוטומטית, קוראים ל-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

סוגים

אפשר לשייך למקום רק סוג ראשי אחד מתוך הסוגים Table A או Table B. לדוגמה, הסוג הראשי יכול להיות 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 ל-50,000.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 מעלות ו-high.longitude= 180 מעלות, אז אזור התצוגה כולל את כל קווי האורך.
  • אם 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, מחזירה את נותני השירות באזור מוגדר במערך התגובה. עסק שנותן שירות באזור מוגדר (SAB) הוא עסק שמספק שירותים או שולח מוצרים לבית הלקוח, אבל לא מספק שירותים בכתובת של העסק.

לדוגמה:

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

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

הצג

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כן

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

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

לא

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

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

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

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

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

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

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

  1. למידע על עלויות, אפשר לעיין במחירונים של Google Maps Platform.

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

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

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

הטיה של מיקום

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

הגבלת מיקום

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

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