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

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

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

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

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

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

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

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

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

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

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

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

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

שאילתה

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

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

סוגים

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

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

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

הבקשה תידחה עם השגיאה INVALID_REQUEST אם:

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

ארצות

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

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

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

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

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

inputOffset

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

locationBias או locationRestriction

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

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

• locationRestriction מציין אזור לחיפוש. לא יוצגו תוצאות מחוץ לאזור שצוין.

מציינים את האזור locationBias או locationRestriction כחלון תצוגה ריבוע או כמעגל.

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

לדוגמה:

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

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

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

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

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

מקור

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

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

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

regionCode

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

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

sessionToken

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

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

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

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

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

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

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

סוגי שימושים

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

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

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

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.

בדוגמה הזו, המקור מוגדר למרכז סן פרנסיסקו:

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 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 והשיוכים.