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

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

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

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

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

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

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

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

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

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

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

הערה: הווידג'ט Autocomplete (New) זמין רק ב-Places Swift SDK ל-iOS בגרסה 10.0.0 ואילך. מידע נוסף זמין במאמר Places Swift for iOS.

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

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

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

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

לדוגמה:

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 (New) כדי לקבל מידע נוסף על כל אחת מהתחזיות של המקומות.

הערה: הווידג'ט Autocomplete (New) זמין רק ב-Places Swift SDK ל-iOS בגרסה 10.0.0 ומעלה. מידע נוסף זמין במאמר Places Swift for iOS.

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

הערה: למידע על מאפייני העיצוב שאפשר להתאים אישית, אפשר לעיין בדף Custom styling ב-UI Kit.

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

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

שימוש בפרמטרים 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
        }
      )
    }
  }
}