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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

שירות ההשלמה האוטומטית (חדש) הוא ממשק 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:^(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:"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:^(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 Attribution.