تکمیل خودکار مکان (جدید)

سرویس تکمیل خودکار (جدید) یک API iOS است که پیشنهادات مکان را در پاسخ به یک درخواست برمی‌گرداند. در درخواست، یک رشته جستجوی متن و مرزهای جغرافیایی که منطقه جستجو را کنترل می کند، مشخص کنید.

سرویس تکمیل خودکار (جدید) می‌تواند با کلمات کامل و زیر رشته‌های ورودی، نام مکان‌ها، آدرس‌ها و کدهای بعلاوه مطابقت داشته باشد. بنابراین برنامه‌ها می‌توانند پرس‌و‌جوهایی را به‌عنوان نوع کاربر ارسال کنند تا پیشنهادات مکانی را در لحظه ارائه دهند.

پیشنهادهای مکان مکان‌هایی هستند، مانند مشاغل، آدرس‌ها و نقاط مورد علاقه، براساس رشته متن ورودی مشخص شده و ناحیه جستجو.

به عنوان مثال، شما API را با استفاده از یک رشته ورودی که شامل ورودی جزئی کاربر، "Sicilian piz" است، با ناحیه جستجو محدود به San Francisco، CA می نامید. سپس پاسخ حاوی لیستی از پیشنهادهای مکان است که با رشته جستجو و منطقه جستجو مطابقت دارد، مانند رستورانی به نام "آشپزخانه پیتزا سیسیلی"، همراه با جزئیات مربوط به مکان.

پیشنهادات مکان بازگشتی به گونه ای طراحی شده است که به کاربر ارائه شود تا بتواند مکان مورد نظر را انتخاب کند. برای دریافت اطلاعات بیشتر در مورد هر یک از پیشنهادات مکان بازگشتی، می‌توانید درخواست جزئیات مکان (جدید) کنید.

درخواست‌های تکمیل خودکار (جدید).

با فراخوانی روشی در GMSPlaceClient یک درخواست تکمیل خودکار ایجاد کنید. شما می توانید پارامترها را در شی GMSAutocompleteRequest ارسال کنید. پاسخ پیشنهادات تکمیل خودکار را در یک شی GMSAutocompletePlaceSuggestion ارائه می دهد.

کلید API و پارامترهای query مورد نیاز است. همچنین می‌توانید GMSAutocompleteSessionToken برای مرتبط کردن درخواست‌ها با جلسه صورت‌حساب و GMSAutocompleteFilter برای اعمال به نتایج اضافه کنید.

برای اطلاعات بیشتر در مورد پارامترهای مورد نیاز و اختیاری، به بخش پارامترهای این سند مراجعه کنید.

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

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 : نام خاص و متن ابهام‌زدا، مانند شهر یا منطقه.

پارامترهای مورد نیاز

پرس و جو

رشته متنی که در آن جستجو می شود. کلمات و رشته های فرعی کامل، نام مکان ها، آدرس ها و کدهای بعلاوه را مشخص کنید. سرویس تکمیل خودکار (جدید) منطبقات نامزد را بر اساس این رشته برمی گرداند و نتایج را بر اساس ارتباط درک شده آنها سفارش می دهد.

پارامترهای اختیاری

انواع

یک مکان فقط می تواند یک نوع اصلی از انواع جدول A یا جدول B مرتبط با آن داشته باشد. به عنوان مثال، نوع اولیه ممکن است mexican_restaurant یا steak_house باشد.

به طور پیش‌فرض، API همه مکان‌ها را بر اساس پارامتر input ، صرف‌نظر از مقدار نوع اولیه مرتبط با مکان، برمی‌گرداند. با پاس دادن پارامتر types ، نتایج را محدود کنید تا از نوع اولیه یا انواع اولیه خاص باشند.

از این پارامتر برای تعیین حداکثر پنج مقدار نوع از جدول A یا جدول 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 را مشخص کنید، نتایج در ناحیه تقاطع دو تنظیمات قرار دارند.

ورودی آفست

افست کاراکتر یونیکد مبتنی بر صفر که موقعیت مکان نما را در 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 به صورت مورب در مقابل هم نمایش داده می شود. یک viewport یک منطقه بسته در نظر گرفته می شود، به این معنی که شامل مرز آن می شود. محدوده عرض جغرافیایی باید بین 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.477398, -74.259087)
let low = CLLocationCoordinate2DMake(40.921628, -73.700051)

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

منطقه کد

کد منطقه ای که برای قالب بندی پاسخ استفاده می شود، به عنوان یک مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده است. اکثر کدهای ccTLD با کدهای ISO 3166-1 یکسان هستند، با برخی استثناهای قابل توجه. برای مثال، ccTLD بریتانیا "uk" (.co.uk) است در حالی که کد ISO 3166-1 آن "gb" است (از لحاظ فنی برای نهاد "پادشاهی متحده بریتانیای کبیر و ایرلند شمالی").

اگر کد منطقه نامعتبر را مشخص کنید، API یک خطای INVALID_ARGUMENT را برمی‌گرداند. این پارامتر می تواند بر نتایج بر اساس قانون قابل اجرا تأثیر بگذارد.

sessionToken

نشانه‌های جلسه رشته‌هایی هستند که توسط کاربر ایجاد می‌شوند که تماس‌های تکمیل خودکار (جدید) را به‌عنوان «جلسه» دنبال می‌کنند. تکمیل خودکار (جدید) از نشانه‌های جلسه برای گروه‌بندی مراحل جستجو و انتخاب جستجوی تکمیل خودکار کاربر در یک جلسه مجزا برای اهداف صورت‌حساب استفاده می‌کند. برای اطلاعات بیشتر، نشانه‌های جلسه را ببینید.

نمونه های تکمیل خودکار (جدید).

از locationRestriction و locationBias استفاده کنید

تکمیل خودکار (جدید) به طور پیش فرض از بایاس IP برای کنترل منطقه جستجو استفاده می کند. با بایاس IP، API از آدرس IP دستگاه برای سوگیری نتایج استفاده می کند. می‌توانید به‌صورت اختیاری از locationRestriction یا locationBias استفاده کنید، اما نه از هر دو، برای تعیین منطقه‌ای برای جستجو.

محدودیت مکان ناحیه مورد جستجو را مشخص می کند. نتایج خارج از منطقه مشخص شده برگردانده نمی شوند. مثال زیر از محدودیت مکان برای محدود کردن درخواست به محدودیت مکان دایره ای با شعاع 5000 متری در مرکز سانفرانسیسکو استفاده می کند:

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

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

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

از انواع استفاده کنید

از پارامتر انواع استفاده کنید تا نتایج یک درخواست از نوع خاصی باشد که در جدول A و جدول B فهرست شده است. شما می توانید یک آرایه تا پنج مقدار را مشخص کنید. در صورت حذف، همه انواع برگردانده می شوند.

مثال زیر یک رشته پرس و جو از "فوتبال" را مشخص می کند و از پارامتر type برای محدود کردن نتایج به تاسیساتی از نوع "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
  // Handle response
})

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

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 مراجعه کنید.