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

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

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

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

לדוגמה, אפשר לשלוח קריאה ל-API באמצעות מחרוזת שמכילה קלט חלקי של המשתמש, "Sicilian piz", כאשר אזור החיפוש מוגבל לסן פרנסיסקו, קליפורניה. התגובה מכילה רשימה של הצעות למקומות שתואמות למחרוזת החיפוש ולאזור החיפוש, כמו המסעדה בשם 'Sicilian Pizza Kitchen' עם פרטים על המקום.

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

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

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

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

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

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

Swift

let token = GMSAutocompleteSessionToken()

let northEastBounds = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWestBounds = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northEastBounds, southWestBounds)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

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

GooglePlacesSwift

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

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

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

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

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

שאילתה

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

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

סוגים

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

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

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

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

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

מדינות

צריך לכלול רק תוצאות מרשימת האזורים שצוינו, המצוינת כמערך של עד 15 ערכים של שני תווים מסוג ccTLD ("top-level domain"). אם לא מזינים, לא חלות הגבלות על התשובה. לדוגמה, כדי להגביל את האזורים לגרמניה ולצרפת:

Swift

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

Objective-C

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

GooglePlacesSwift

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

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

inputOffset

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

טירגוט לפי מיקום או הגבלת מיקום

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

למשל:

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

GooglePlacesSwift

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

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

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

Swift

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

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

GooglePlacesSwift

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

מקור

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

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

GooglePlacesSwift

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

regionCode

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

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

sessionToken

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

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

שימוש בהגבלת מיקום וב-locationBias

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

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

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:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
  })

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

GooglePlacesSwift

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.locationBias = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

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

GooglePlacesSwift

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

סוגי שימושים

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

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

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
  // Handle response
})

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

GooglePlacesSwift

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

שימוש במקור

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

בדוגמה הזו מגדירים את נקודת המוצא כמרכז סן פרנסיסקו:

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
  // Handle response
})

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

GooglePlacesSwift

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

שיוכים

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