שירות ההשלמה האוטומטית (חדש) הוא ממשק API ל-iOS ומחזירה הצעות למקומות בתגובה לבקשה. בבקשה, מציינים מחרוזת חיפוש טקסט וגבולות גיאוגרפיים ששולטים באזור החיפוש.
שירות ההשלמה האוטומטית (חדש) יכול להתאים באופן מלא מילים ומחרוזות משנה של הקלט, לפתרון שמות של מקומות, כתובות ופלוס קודים. לכן האפליקציות יכולות לשלוח שאילתות בתור המשתמש כדי לספק הצעות למקומות בזמן אמת.
הצעות למקומות הן מקומות, כמו עסקים, כתובות ונקודות של על סמך מחרוזת טקסט הקלט ואזור החיפוש שצוינו.
לדוגמה, אפשר לקרוא ל-API על ידי שימוש במחרוזת שמכילה חלק קלט של משתמשים, "Spagh", כאשר אזור החיפוש מוגבל לעיר ניו יורק. התשובה תכיל רשימה של הצעות למקומות שתואמים לחיפוש מחרוזת ואזור חיפוש, למשל המסעדה "Cafe Spaghetti", יחד עם פרטים על המקום.
ההצעות למקומות שמוחזרות נועדו להופיע בפני המשתמש, שהם יוכלו לבחור את המקום הרצוי. ניתן ליצור פרטי מקום (חדש) בקשה לקבלת עוד מידע על אחת מההצעות שהוחזרו למקומות.
בקשות להשלמה אוטומטית (חדש)
צרו בקשה להשלמה אוטומטית על ידי קריאה לשיטה
GMSPlaceClient
אפשר להעביר פרמטרים
GMSAutocompleteRequest
לאובייקט. התשובה מספקת הצעות להשלמה אוטומטית בתוך
GMSAutocompletePlaceSuggestion
לאובייקט.
מפתח ה-API והפרמטרים query
נדרשים. אפשר גם לכלול
GMSAutocompleteSessionToken
כדי לשייך בקשות לסשן חיוב
GMSAutocompleteFilter
כדי ליישם את התוצאות.
מידע נוסף על פרמטרים נדרשים ואופציונליים זמין בקטע הפרמטרים במסמך הזה.
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. } } }];
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
: השם הספציפי והטקסט שייחודי לו, כמו עיר או אזור.
פרמטרים נדרשים
שאילתה
מחרוזת הטקסט שבה יש לחפש. ציון מילים שלמות ומחרוזות משנה, מקום שמות, כתובות וקודי OLC. שירות השלמה אוטומטית (חדש) מחזיר התאמות אפשריות על סמך המחרוזת הזו, ומסדרים את התוצאות על סמך הרלוונטיות לכאורה שלהן.
פרמטרים אופציונליים
סוגים
למקום יכול להיות רק סוג ראשי יחיד מהסוגים טבלה
A או טבלה
ב המשויך אליו.
לדוגמה, הסוג הראשי יכול להיות mexican_restaurant
או steak_house
.
כברירת מחדל, ה-API מחזיר את כל המקומות על סמך הפרמטר input
,
ללא קשר לערך של הסוג הראשי שמשויך למקום. הגבלת התוצאות
להיות מסוג ראשי מסוים או מסוג ראשי, על ידי העברת
הפרמטר types
.
אפשר להשתמש בפרמטר הזה כדי לציין עד חמישה סוגי ערכים בעמודה טבלה A או טבלה ב. המקום צריך להיות תואם אחד מערכי הסוג הראשי שצוינו שייכללו בתשובה.
הבקשה נדחית ותוצג השגיאה INVALID_REQUEST
אם:
- ציינת יותר מחמישה סוגים.
- כל הסוגים לא מזוהים.
ארצות
הכללת תוצאות מרשימת האזורים שצוינו בלבד, המצוינת כמערך של עד 15 ccTLD ("ברמה העליונה" דומיין") בשני תווים. אם לא מזינים, לא חלות הגבלות על התשובה. לדוגמה, כדי להגביל את האזורים לגרמניה ולצרפת:
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
מציין את האזור לחיפוש. תוצאות מחוץ ל- השטח שצוין לא מוחזר.
צריך לציין את האזור locationBias
או locationRestriction
כמלבן
אזור תצוגה או כעיגול.
מעגל מוגדר לפי נקודת המרכז והרדיוס במטרים. הרדיוס חייב להיות
בין 0.0 ל-50000.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.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);
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 ("ברמה העליונה" דומיין") בשני תווים. רוב קודי ה-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:"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:^(NSArrayG<MSAutocompleteSuggestion * >* 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:"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. } } }];
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 כדי להגביל את התוצאות מבקשה לערך מסוים הקלד כפי שמפורט בטבלה A וטבלה ב. אפשר לציין של עד חמישה ערכים. אם לא צוין, יוחזרו כל הסוגים.
הדוגמה הבאה מציינת את מחרוזת השאילתה "כדורגל" והוא משתמש בסוגי
פרמטר להגבלת התוצאות למוסדות מסוג
"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 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. } } }];
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 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:^(NSArrayG<MSAutocompleteSuggestion * >* 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 Attribution.