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

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

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

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

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

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

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

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

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

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

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

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

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

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.
}

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

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: השם הספציפי והטקסט להפגת העמימות, כמו עיר או אזור.

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

שאילתה

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

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

sessionToken

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

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

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)")

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:

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

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

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

ארצות

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

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

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

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. אחרת, הבקשה לא מחזירה תוצאות.

לדוגמה:

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

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

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

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, והתיבה שמיוצגת לא יכולה להיות ריקה. אם אזור התצוגה ריק, תופיע שגיאה.

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

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

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

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

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). אם הערך הזה מושמט, המרחק בקו ישר לא יוחזר. צריך לציין את המיקום בקואורדינטות של קו רוחב וקו אורך:

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

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

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) בלבד. עסק שנותן שירות באזור מוגדר (SAB) הוא עסק שמספק את השירות בכתובת של הלקוחות או שולח את המוצר ישירות אליהם, אבל לא מספק שירות בכתובת העסק.

לדוגמה:

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

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

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

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

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

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

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

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

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

הצג

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

onSelection

ה-closure שמופעל כשבוחרים מקום.

onError

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

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

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

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

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

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

שימוש ב-locationRestriction וב-locationBias

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

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

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.
}
  

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

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.
    }
  }
}];

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

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.
}
  

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

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 כדי להגביל את התוצאות מבקשה לסוג מסוים, כמו שמפורט בטבלה א' ובטבלה ב'. אפשר לציין מערך של עד חמישה ערכים. אם לא מציינים סוג, מוחזרים כל הסוגים.

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

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.
}
    

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

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.

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

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.
}
  

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

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.
      }
    }
}];

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

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

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

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 יחזיר שגיאה.
• חשוב לוודא שהאפליקציה מטפלת במקרים שבהם אין בחירה ומציעה למשתמשים דרך להמשיך.

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

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

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

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

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

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

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

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

השלמה אוטומטית מבוססת-סשן (חדש) עם Place Details (חדש)

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

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

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

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

השלמה אוטומטית (חדשה) לכל בקשה באמצעות Geocoding API

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

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

השלמה אוטומטית (חדשה) מבוססת-סשן לאפליקציות של כתובות בלבד

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

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

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

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

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

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

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

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

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

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

הטיה לפי מיקום

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

הגבלת מיקום

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

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