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

پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت، وب سرویس

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

برای مثال، شما API را با استفاده از رشته‌ای که شامل بخشی از ورودی کاربر، "Spagh" است و ناحیه جستجو به شهر نیویورک محدود شده است، فراخوانی می‌کنید. سپس پاسخ شامل فهرستی از پیشنهادهای مکان است که با رشته جستجو و ناحیه جستجو مطابقت دارند، مانند رستورانی به نام "Cafe Spaghetti"، به همراه جزئیاتی در مورد مکان.

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

شما می‌توانید قابلیت تکمیل خودکار (جدید) را به دو روش اصلی در برنامه خود ادغام کنید:

پیش‌بینی‌های مکان را به صورت برنامه‌نویسی‌شده دریافت کنید

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

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

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

نسخه SDK سوئیفت را قرار می‌دهد

با فراخوانی یک متد در PlacesClient یک درخواست تکمیل خودکار ایجاد کنید. می‌توانید پارامترها را در شیء AutocompleteRequest ارسال کنید. پاسخ، پیشنهادات تکمیل خودکار را در یک شیء AutocompletePlaceSuggestion ارائه می‌دهد.

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

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

مکان‌های Swift SDK

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

سویفت

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

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

تابع تکمیل خودکار، آرایه‌ای شامل حداکثر پنج نمونه از GMSAutocompleteSuggestion را برمی‌گرداند. این آرایه شامل موارد زیر است:

  • placeID
  • types : انواعی که در مورد این مکان صدق می‌کنند.
  • distanceMeters : فاصله از مبدا.
  • attributedFullText : متن کامل و خوانا برای انسان از یک پیشنهاد.
  • attributedPrimaryText : متن اصلی قابل خواندن توسط انسان از یک پیشنهاد.
  • attributedSecondaryText : متن ثانویه‌ی قابل خواندن توسط انسان از یک پیشنهاد.
  • structuredFormat : نام خاص و متن ابهام‌زدایی، مانند شهر یا منطقه.

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

پرس و جو

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

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

توکن جلسه

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

شما می‌توانید توکن نشست Places Autocomplete خود را در معرض نمایش قرار دهید تا آن را به سرویس‌های دیگری که بخشی از Places SDK برای iOS نیستند، مانند Address Validation، منتقل کنید:

مکان‌های Swift SDK

let token = AutocompleteSessionToken()
let filter = AutocompleteFilter(origin: CLLocationCoordinate2DMake(39.7, -94.5))
let request = AutocompleteRequest(query: "Piz", sessionToken: token, filter: filter)

PlacesClient.shared.fetchAutocompleteSuggestions(request: request) {
    case .success(let suggestions):
      ...
    case .failure(let placesError):
      print(placesError) 
}

// pass token's string format to use with a service that is not a part of iOS SDK.
print("token: \(token)")

هدف-سی

GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Piz"];
GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init];
request.sessionToken = token;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:39.7 longitude:-94.5];
filter.locationBias = GMSPlaceRectangularLocationOption(topLocation, bottomLocation);

request.filter = filter;
 [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request
                     callback:^(NSArray<GMSAutocompleteSuggestion *> *_Nullable results,
                                NSError *_Nullable error) {
  ...
}];

// pass token's string format to use with a service that is not a part of iOS SDK.
NSLog(@"%@", token.description);

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

پارامترهای اختیاری فیلتر تکمیل خودکار

انواع

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

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

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

درخواست با خطای INVALID_REQUEST رد می‌شود اگر:

  • بیش از پنج نوع مشخص شده است.
  • هر نوع ناشناخته‌ای مشخص شده است.

برای مثال، برای محدود کردن نتایج به فروشگاه‌های لوازم ورزشی، آن نوع را در AutocompleteFilter خود مشخص کنید:

مکان‌های Swift SDK

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
  

سویفت

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
  

هدف-سی

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];

کشورها

فقط نتایجی از لیست مناطق مشخص شده را در نظر بگیرید، که به صورت آرایه‌ای با حداکثر ۱۵ مقدار دو کاراکتری ccTLD ("دامنه سطح بالا") مشخص شده‌اند. در صورت حذف، هیچ محدودیتی برای پاسخ اعمال نمی‌شود. به عنوان مثال، برای محدود کردن مناطق به آلمان و فرانسه:

مکان‌های Swift SDK

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

سویفت

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

هدف-سی

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

اگر هم locationRestriction و هم countries مشخص کنید، نتایج در ناحیه تقاطع این دو تنظیم قرار می‌گیرند.

ورودی-آفست

آفست کاراکتر یونیکد مبتنی بر صفر که موقعیت مکان‌نما را در input نشان می‌دهد. موقعیت مکان‌نما می‌تواند بر پیش‌بینی‌های برگشتی تأثیر بگذارد. اگر خالی باشد، به طور پیش‌فرض به طول input تنظیم می‌شود.

سوگیری مکانی یا محدودیت مکانی

شما می‌توانید locationBias یا locationRestriction برای تعریف ناحیه جستجو مشخص کنید، اما نه هر دو را. locationRestriction را به عنوان مشخص کننده ناحیه‌ای که نتایج باید درون آن باشند، و locationBias به عنوان مشخص کننده ناحیه‌ای که نتایج باید نزدیک به آن باشند اما می‌توانند خارج از آن ناحیه باشند، در نظر بگیرید.

  • locationBias یک منطقه برای جستجو را مشخص می‌کند. این مکان به عنوان یک bias عمل می‌کند، به این معنی که نتایج اطراف مکان مشخص شده، از جمله نتایج خارج از منطقه مشخص شده، می‌توانند بازگردانده شوند.

  • locationRestriction محدوده‌ای را برای جستجو مشخص می‌کند. نتایج خارج از محدوده‌ی مشخص شده بازگردانده نمی‌شوند.

ناحیه locationBias یا locationRestriction را به عنوان یک نمای مستطیلی یا به عنوان یک دایره مشخص کنید.

یک دایره با نقطه مرکزی و شعاع بر حسب متر تعریف می‌شود. شعاع باید بین 0.0 تا 50000.0 باشد، که شامل همه می‌شود. مقدار پیش‌فرض 0.0 است. برای locationRestriction ، باید شعاع را روی مقداری بزرگتر از 0.0 تنظیم کنید. در غیر این صورت، درخواست هیچ نتیجه‌ای برنمی‌گرداند.

برای مثال:

مکان‌های Swift SDK

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

سویفت

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

مستطیل، یک دریچه دید طول و عرض جغرافیایی است که به صورت دو نقطه low و high که به صورت مورب روبروی هم قرار دارند، نمایش داده می‌شود. یک دریچه دید، یک منطقه بسته در نظر گرفته می‌شود، به این معنی که شامل مرز خود نیز می‌شود. محدوده‌های عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه و محدوده‌های طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشند:

  • اگر low = high ، نمای دید از آن نقطه واحد تشکیل شده است.
  • اگر low.longitude > high.longitude ، محدوده طول جغرافیایی معکوس می‌شود (صفحه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند).
  • اگر low.longitude = -180 درجه و high.longitude = 180 درجه باشد، صفحه نمایش شامل تمام طول‌های جغرافیایی می‌شود.
  • اگر low.longitude = 180 درجه و high.longitude = -180 درجه باشد، محدوده طول جغرافیایی خالی است.

هر دو پارامتر low و high باید پر شوند و کادر نمایش داده شده نمی‌تواند خالی باشد. یک viewport خالی منجر به خطا می‌شود.

برای مثال، این نمای کلی، شهر نیویورک را به طور کامل در بر می‌گیرد:

مکان‌های Swift SDK

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

سویفت

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

منشأ

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

مکان‌های Swift SDK

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

سویفت

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

کد منطقه

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

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

shouldIncludePureServiceAreaBusinesses

اگر true ، کسب‌وکارهای صرفاً خدماتی را در آرایه پاسخ برمی‌گرداند. یک کسب‌وکار صرفاً خدماتی، کسب‌وکاری است که مستقیماً از مشتریان بازدید می‌کند یا به آنها خدمات ارائه می‌دهد، اما به مشتریان در آدرس کسب‌وکارشان خدمات ارائه نمی‌دهد.

برای مثال:

مکان‌های Swift SDK

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

سویفت

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

هدف-سی

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.shouldIncludePureServiceAreaBusinesses = YES;

ویجت تکمیل خودکار مکان را اضافه کنید

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

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

همانند زمانی که پیش‌بینی‌های مکان را به صورت برنامه‌نویسی دریافت می‌کنید ، ویجت Place Autocomplete به شما امکان می‌دهد از توکن‌های جلسه برای گروه‌بندی درخواست‌های تکمیل خودکار در جلسه برای اهداف صدور صورتحساب استفاده کنید. می‌توانید با فراخوانی AutocompleteSessionToken() یک توکن جلسه ارسال کنید.

اگر نشانه جلسه (session token) ارائه ندهید، ویجت یک نشانه جلسه تکمیل خودکار (Autocomplete session token) برای شما ایجاد می‌کند که می‌توانید آن را از طریق فراخوانی onSelection دریافت کنید. برای اطلاعات بیشتر در مورد استفاده از نشانه جلسه (session tokens)، به بخش «درباره نشانه جلسه» (About session tokens) مراجعه کنید.

وقتی مقدار show binding روی true تنظیم شود، کاربر به یک نمای تمام صفحه هدایت می‌شود که در آن می‌تواند یک مکان را انتخاب کند. همزمان با تایپ کاربر، ویجت پیشنهادهایی برای مکان‌هایی مانند کسب و کارها، آدرس‌ها و نقاط مورد علاقه برمی‌گرداند. وقتی کاربر مکانی را انتخاب می‌کند، ویجت، هندلر onSelection را با مکان انتخاب شده فراخوانی می‌کند و نمای تمام صفحه را می‌بندد.

پارامترهای ویجت تکمیل خودکار را قرار دهید

علاوه بر پارامترهای موجود در برنامه‌نویسی ، ویجت Place Autocomplete پارامترهای زیر را نیز ارائه می‌دهد.

نشان دادن

show مشخص می‌کند که آیا ویجت نمایش داده شود یا خیر.

انتخاب

تابع closure که هنگام انتخاب یک مکان اجرا می‌شود.

خطای onError

تابع closure هنگام بروز خطا اجرا می‌شود. در صورت بروز خطا، یک PlacesError ارسال می‌شود.

سفارشی‌سازی محتوا و قالب

پارامترهای AutocompleteUICustomization سفارشی‌سازی‌های رابط کاربری را برای اعمال روی ویجت مشخص می‌کنند. گزینه‌های سفارشی‌سازی عبارتند از:

  • AutocompleteListDensity . این پارامتر به شما امکان می‌دهد چگالی لیست پیشنهادات را، چه به multiLine و چه به twoLine ، انتخاب کنید.
  • AutocompleteUIIcon . این پارامتر به شما امکان می‌دهد انتخاب کنید که آیا آیکون پیش‌فرض برای هر آیتم لیست نمایش داده شود یا خیر.
  • theme . این پارامتر یک تم سفارشی را مشخص می‌کند که هر یک از ویژگی‌های پیش‌فرض استایل را لغو می‌کند. می‌توانید رنگ‌ها، تایپوگرافی، فاصله‌گذاری، حاشیه‌ها و گوشه‌های کامپوننت Place Autocomplete خود را سفارشی کنید. پیش‌فرض PlacesMaterialTheme است. هر ویژگی تم که لغو نشده باشد، از استایل‌های پیش‌فرض استفاده می‌کند.

یک مثال کامل از کد را ببینید .

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

استفاده از locationRestriction و locationBias

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

محدودیت مکان، ناحیه مورد جستجو را مشخص می‌کند. نتایج خارج از ناحیه مشخص شده بازگردانده نمی‌شوند. مثال زیر از محدودیت مکان برای محدود کردن درخواست به یک محدودیت مکانی دایره‌ای با شعاع ۵۰۰۰ متر با محوریت سانفرانسیسکو استفاده می‌کند:

مکان‌های Swift SDK

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

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

مکان‌های Swift SDK

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

سویفت

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

انواع استفاده

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

مثال زیر یک رشته پرس‌وجو از نوع "Soccer" را مشخص می‌کند و از پارامتر types برای محدود کردن نتایج به فروشگاه‌هایی از نوع "sporting_goods_store" استفاده می‌کند:

مکان‌های Swift SDK

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

سویفت

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

از مبدا استفاده کنید

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

این مثال مبدا را روی مرکز سانفرانسیسکو تنظیم می‌کند:

مکان‌های Swift SDK

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

سویفت

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 uiCustomization = AutocompleteUICustomization(
    listDensity: .multiLine,
    listItemIcon: .noIcon,
    theme: PlacesMaterialTheme()
)

افزودن ویجت تکمیل خودکار مکان‌ها (کد کامل)

مکان‌های Swift SDK

struct PlaceAutocompleteDemoView: View {

  @State private var fetchedPlace: Place?
  @State private var placesError: PlacesError?
  @State private var showWidget = false

  public var body: some View {
    VStack {
      Button("Search for a place") {
        showWidget.toggle()
      }
      .placeAutocomplete(
        show: $showWidget,
        onSelection: { (autocompletePlaceSuggestion, autocompleteSessionToken) in
          Task {
            let placesClient = await PlacesClient.shared
            let fetchPlaceRequest = FetchPlaceRequest(
              placeID: autocompletePlaceSuggestion.placeID,
              placeProperties: [.displayName, .formattedAddress],
              sessionToken: autocompleteSessionToken
            )

            switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
            case .success(let place):
              print("Fetched place: \(place)")
              self.fetchedPlace = place
            case .failure(let placesError):
              print("Failed to fetch place: \(placesError)")
              self.placesError = placesError
            }
          }
        },
        onError: { placesError in
          self.placesError = placesError
        }
      )
    }
  }
}

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

این بخش بهترین شیوه‌ها را برای کمک به شما در استفاده بهینه از سرویس تکمیل خودکار (جدید) شرح می‌دهد.

در اینجا چند دستورالعمل کلی آورده شده است:

بهترین شیوه‌های بهینه‌سازی هزینه

بهینه‌سازی هزینه پایه

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

بهینه‌سازی پیشرفته هزینه

پیاده‌سازی برنامه‌ریزی‌شده‌ی Autocomplete (جدید) را برای دسترسی به SKU در نظر بگیرید: Autocomplete درخواست قیمت‌گذاری و درخواست نتایج Geocoding API در مورد مکان انتخاب‌شده به جای Place Details (جدید). قیمت‌گذاری بر اساس درخواست همراه با Geocoding API در صورت برآورده شدن هر دو شرط زیر، مقرون‌به‌صرفه‌تر از قیمت‌گذاری بر اساس هر جلسه (مبتنی بر جلسه) است:

  • اگر فقط به طول/عرض جغرافیایی یا آدرس مکان انتخاب شده کاربر نیاز دارید، API مربوط به Geocoding این اطلاعات را با هزینه‌ای کمتر از فراخوانی Place Details (New) ارائه می‌دهد.
  • اگر کاربران به طور متوسط ​​از بین چهار درخواست پیش‌بینی تکمیل خودکار (جدید) یا کمتر، یک پیش‌بینی تکمیل خودکار را انتخاب کنند، قیمت‌گذاری بر اساس هر درخواست ممکن است مقرون به صرفه‌تر از قیمت‌گذاری بر اساس هر جلسه باشد.
برای کمک به انتخاب پیاده‌سازی تکمیل خودکار (جدید) که متناسب با نیازهای شما باشد، برگه‌ای را که مربوط به پاسخ شما به سوال زیر است، انتخاب کنید.

آیا درخواست شما به اطلاعات دیگری غیر از آدرس و طول و عرض جغرافیایی پیش‌بینی انتخاب شده نیاز دارد؟

بله، نیاز به توضیحات بیشتر دارد

استفاده از تکمیل خودکار مبتنی بر جلسه (جدید) به همراه جزئیات مکان (جدید).
از آنجایی که برنامه شما به جزئیات مکان (جدید)، مانند نام مکان، وضعیت کسب و کار یا ساعات کاری نیاز دارد، پیاده‌سازی Autocomplete (جدید) شما باید از یک توکن جلسه (به صورت برنامه‌نویسی یا ساخته شده در ویجت‌های جاوا اسکریپت ، اندروید یا iOS ) به ازای هر جلسه به علاوه SKU های مکان‌های قابل اجرا، بسته به فیلدهای داده مکانی که درخواست می‌کنید، استفاده کند. 1

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

پیاده‌سازی برنامه‌ریزی‌شده
از یک توکن جلسه ( session token) برای درخواست‌های تکمیل خودکار (Autocomplete) خود استفاده کنید. هنگام درخواست جزئیات مکان (Place Details) (جدید) در مورد پیش‌بینی انتخاب شده، پارامترهای زیر را وارد کنید:

  1. شناسه مکان از پاسخ تکمیل خودکار (جدید)
  2. توکن جلسه مورد استفاده در درخواست تکمیل خودکار (جدید)
  3. پارامتر fields که فیلدهای داده تکمیل خودکار (جدید) مورد نیاز شما را مشخص می‌کند

خیر، فقط به آدرس و موقعیت مکانی نیاز دارد

بسته به عملکرد استفاده از Autocomplete (جدید)، API مربوط به Geocoding می‌تواند گزینه مقرون‌به‌صرفه‌تری نسبت به Place Details (جدید) برای برنامه شما باشد. کارایی Autocomplete (جدید) هر برنامه بسته به اینکه کاربران چه اطلاعاتی را وارد می‌کنند، برنامه در کجا استفاده می‌شود و اینکه آیا بهترین شیوه‌های بهینه‌سازی عملکرد پیاده‌سازی شده‌اند یا خیر، متفاوت است.

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

آیا کاربران شما به طور متوسط ​​​​در چهار درخواست یا کمتر، پیش‌بینی تکمیل خودکار (جدید) را انتخاب می‌کنند؟

بله

تکمیل خودکار (جدید) را به صورت برنامه‌نویسی شده و بدون توکن‌های جلسه پیاده‌سازی کنید و API مربوط به Geocoding را روی پیش‌بینی مکان انتخاب شده فراخوانی کنید.
API ژئوکدینگ آدرس‌ها و مختصات طول و عرض جغرافیایی را ارائه می‌دهد. انجام چهار درخواست تکمیل خودکار به همراه یک فراخوانی API ژئوکدینگ در مورد پیش‌بینی مکان انتخاب شده، کمتر از هزینه تکمیل خودکار (جدید) به ازای هر جلسه است. 1

در نظر داشته باشید که از بهترین شیوه‌های عملکرد استفاده کنید تا به کاربران خود کمک کنید پیش‌بینی مورد نظر خود را با تعداد کاراکترهای کمتری دریافت کنند.

خیر

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

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

پیاده‌سازی برنامه‌ریزی‌شده
از یک توکن جلسه ( session token) برای درخواست‌های تکمیل خودکار (Autocomplete) خود استفاده کنید. هنگام درخواست جزئیات مکان (Place Details) (جدید) در مورد پیش‌بینی انتخاب شده، پارامترهای زیر را وارد کنید:

  1. شناسه مکان از پاسخ تکمیل خودکار (جدید)
  2. توکن جلسه مورد استفاده در درخواست تکمیل خودکار (جدید)
  3. پارامتر fields که فیلدهایی مانند آدرس و هندسه را مشخص می‌کند

درخواست‌های تکمیل خودکار (جدید) را به تعویق بیندازید
شما می‌توانید از استراتژی‌هایی مانند به تأخیر انداختن درخواست تکمیل خودکار (جدید) تا زمانی که کاربر سه یا چهار کاراکتر اول را تایپ کرده باشد، استفاده کنید تا برنامه شما درخواست‌های کمتری ارسال کند. به عنوان مثال، ایجاد درخواست‌های تکمیل خودکار (جدید) برای هر کاراکتر پس از تایپ کاراکتر سوم توسط کاربر به این معنی است که اگر کاربر هفت کاراکتر تایپ کند و سپس پیش‌بینی‌ای را انتخاب کند که شما برای آن یک درخواست API Geocoding ارسال می‌کنید، هزینه کل برای 4 تکمیل خودکار (جدید) به ازای هر درخواست + Geocoding خواهد بود. 1

اگر تأخیر در درخواست‌ها می‌تواند میانگین درخواست برنامه‌نویسی شما را به زیر چهار برساند، می‌توانید از راهنمایی‌های مربوط به تکمیل خودکار (جدید) با پیاده‌سازی API Geocoding پیروی کنید. توجه داشته باشید که تأخیر در درخواست‌ها می‌تواند توسط کاربری که انتظار دارد با هر ضربه کلید جدید، پیش‌بینی‌ها را ببیند، به عنوان تأخیر تلقی شود.

استفاده از بهترین شیوه‌های عملکرد را در نظر بگیرید تا به کاربران خود کمک کنید پیش‌بینی مورد نظر خود را با تعداد کاراکترهای کمتری دریافت کنند.


  1. برای اطلاع از هزینه‌ها، به لیست قیمت‌های پلتفرم نقشه‌های گوگل مراجعه کنید.

بهترین شیوه‌های عملکرد

دستورالعمل‌های زیر روش‌های بهینه‌سازی عملکرد تکمیل خودکار (جدید) را شرح می‌دهند:

  • محدودیت‌های کشور، سوگیری موقعیت مکانی و (برای پیاده‌سازی‌های برنامه‌نویسی) ترجیح زبان را به پیاده‌سازی تکمیل خودکار (جدید) خود اضافه کنید. ترجیح زبان با ویجت‌ها لازم نیست زیرا آن‌ها ترجیحات زبان را از مرورگر یا دستگاه تلفن همراه کاربر انتخاب می‌کنند.
  • اگر تکمیل خودکار (جدید) با نقشه همراه باشد، می‌توانید مکان را بر اساس نمای نقشه تغییر دهید.
  • در شرایطی که کاربر یکی از پیش‌بینی‌های تکمیل خودکار (جدید) را انتخاب نمی‌کند، عموماً به این دلیل که هیچ‌کدام از این پیش‌بینی‌ها آدرس-نتیجه مورد نظر نیستند، می‌توانید از ورودی اصلی کاربر برای تلاش جهت دریافت نتایج مرتبط‌تر استفاده مجدد کنید:
    • اگر انتظار دارید کاربر فقط اطلاعات آدرس را وارد کند، از ورودی اصلی کاربر در فراخوانی Geocoding API استفاده مجدد کنید.
    • اگر انتظار دارید کاربر برای یک مکان خاص با نام یا آدرس جستجو کند، از درخواست «جزئیات مکان (جدید)» استفاده کنید. اگر نتایج فقط در یک منطقه خاص مورد انتظار است، از «سوگیری مکان» استفاده کنید.
    سناریوهای دیگری که در آنها بهتر است به API ژئوکدینگ برگردیم عبارتند از:
    • کاربرانی که آدرس‌های فرعی، مانند آدرس‌های واحدها یا آپارتمان‌های خاص در یک ساختمان را وارد می‌کنند. برای مثال، آدرس چکی "Stroupežnického 3191/17, Praha" در حالت تکمیل خودکار (جدید) پیش‌بینی جزئی ارائه می‌دهد.
    • کاربرانی که آدرس‌هایی با پیشوندهای قطعه جاده‌ای مانند «خیابان بیست و نهم، شماره ۲۳-۳۰، کوئینز» در شهر نیویورک یا «بزرگراه کامهامها، شماره ۴۷-۳۸۰، کانئوهه» در جزیره کائوآئی در هاوایی وارد می‌کنند.

سوگیری مکانی

با ارسال پارامتر location و پارامتر radius ، نتایج را به یک منطقه مشخص شده متمایل می‌کند. این به Autocomplete (جدید) دستور می‌دهد که ترجیح دهد نتایج را در منطقه تعریف شده نشان دهد. نتایج خارج از منطقه تعریف شده همچنان ممکن است نمایش داده شوند. می‌توانید از پارامتر components برای فیلتر کردن نتایج استفاده کنید تا فقط مکان‌های داخل یک کشور مشخص شده را نشان دهد.

محدود کردن موقعیت مکانی

با ارسال پارامتر locationRestriction ، نتایج را به یک ناحیه مشخص محدود کنید.

همچنین می‌توانید با اضافه کردن پارامتر locationRestriction ، نتایج را به ناحیه‌ای که توسط location و پارامتر radius تعریف شده است، محدود کنید. این به Autocomplete (جدید) دستور می‌دهد که فقط نتایج درون آن ناحیه را برگرداند.