الإكمال التلقائي للأماكن (جديد)

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

خدمة "الإكمال التلقائي (جديد)" هي واجهة برمجة تطبيقات لنظام التشغيل iOS تهدف إلى عرض اقتراحات بشأن الأماكن استجابةً لطلب. في الطلب، حدِّد سلسلة بحث نصيّة وحدودًا جغرافية تتحكّم في منطقة البحث.

يمكن لخدمة "الإكمال التلقائي (الإصدار الجديد)" مطابقة الكلمات الكاملة والسلسلة الفرعية للنص الذي يتم إدخاله، وحلّ أسماء الأماكن والعناوين ورموز ميزة "إضافة". وبالتالي، يمكن للتطبيقات إرسال طلبات بحث أثناء كتابة المستخدمين، لتوفير اقتراحات فورية عن الأماكن.

الأماكن المقترَحة هي أماكن، مثل الأنشطة التجارية والعناوين ونقاط ازدحام، استنادًا إلى سلسلة نص الإدخال المحدّدة ومنطقة البحث.

على سبيل المثال، يمكنك استدعاء واجهة برمجة التطبيقات باستخدام سلسلة تحتوي على إدخال جزئي من المستخدِم، "Spagh"، مع حصر منطقة البحث في مدينة القاهرة. يحتوي الردّ بعد ذلك على قائمة باقتراحات الأماكن التي تتطابق مع سلسلة البحث و منطقة البحث، مثل المطعم المُسمى "Cafe Spaghetti"، بالإضافة إلى تفاصيل عن المكان.

تم تصميم اقتراحات الأماكن المعروضة ليتم تقديمها للمستخدمين كي تتمكّنوا من اختيار المكان المطلوب. يمكنك تقديم طلب تفاصيل الأماكن (جديد) للحصول على المزيد من المعلومات عن أيّ من اقتراحات الأماكن المعروضة.

يمكنك دمج وظائف ميزة "الإكمال التلقائي (جديد)" في تطبيقك بطريقتَين أساسيتَين:

الحصول على توقّعات الأماكن آليًا

طلبات الإكمال التلقائي (جديد)

أنشئ طلب إكمال تلقائي من خلال استدعاء طريقة في GMSPlacesClient. يمكنك تمرير المَعلمات في العنصر GMSAutocompleteRequest. يقدّم الردّ اقتراحات للإكمال التلقائي ضمن عنصر GMSAutocompletePlaceSuggestion.

مفتاح واجهة برمجة التطبيقات ومَعلمة query مطلوبة. يمكنك أيضًا تضمين GMSAutocompleteSessionToken لربط الطلبات بجلسة فوترة و GMSAutocompleteFilter للتطبيق على النتائج.

إصدار حزمة تطوير البرامج (SDK) لبرنامج Places Swift

أنشئ طلب إكمال تلقائي من خلال استدعاء طريقة في PlacesClient. يمكنك تمرير المَعلمات في العنصر AutocompleteRequest. يقدّم الردّ اقتراحات للإكمال التلقائي ضمن عنصر AutocompletePlaceSuggestion.

مفتاح واجهة برمجة التطبيقات ومَعلمة query مطلوبان. يمكنك أيضًا تضمين AutocompleteSessionToken لربط الطلبات بجلسة فوترة و AutocompleteFilter للتطبيق على النتائج.

لمزيد من المعلومات عن المَعلمات المطلوبة والاختيارية، يُرجى الاطّلاع على قسم المَعلمات في هذا المستند.

حزمة تطوير البرامج (SDK) لأماكن Swift

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

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

الردود التي يتم إكمالها تلقائيًا (جديدة)

تعرض ميزة "الإكمال التلقائي" صفيفًا يتضمّن ما يصل إلى خمس نُسخ GMSAutocompleteSuggestion. تحتوي الصفيف على ما يلي:

  • placeID
  • types: الأنواع التي تنطبق على هذا المكان
  • distanceMeters: المسافة من نقطة المبدأ
  • attributedFullText: النص الكامل المقترَح والذي يمكن لشخص عادي قراءته
  • attributedPrimaryText: النص الأساسي القابل للقراءة من قِبل البشر لاقتراح معيّن
  • attributedSecondaryText: نص ثانوي يسهل قراءته يوضّح الاقتراح
  • structuredFormat: الاسم المحدّد والنص الذي يزيل الالتباس، مثل مدينة أو منطقة

المعلمات المطلوبة

query

سلسلة النصوص المطلوب البحث فيها. حدِّد الكلمات الكاملة والسلسلة الفرعية وأسماء المواقع الجغرافية والعناوين ورموز المواقع المفتوحة. تعرض خدمة الإكمال التلقائي (الجديدة) مطابقات مرشحة استنادًا إلى هذه السلسلة وترتيب النتائج استنادًا إلى مدى صلتها بالمعلومات التي تم البحث عنها.

المعلمات الاختيارية

sessionToken

علامات الجلسات هي سلاسل ينشئها المستخدمون وتتتبّع طلبات "الإكمال التلقائي (جديد)"، سواءً كانت طلبات تم إجراؤها من خلال التطبيق المصغّر أو الطلبات الآلية، على أنّها "جلسات". تستخدِم ميزة "الإكمال التلقائي (جديد)" الرموز المميّزة للجلسات لتجميع مرحلتَي الطلب والاختيار في عملية بحث الإكمال التلقائي الخاصة بالمستخدم في جلسة منفصلة لأغراض الفوترة. لمزيد من المعلومات، يُرجى الاطّلاع على علامات الجلسة.

مَعلمات AutocompleteFilter الاختيارية

الأنواع

لا يمكن أن يتضمّن المكان سوى نوع أساسي واحد من النوعَين جدول أ أو جدول ب المرتبط به. على سبيل المثال، قد يكون النوع الأساسي mexican_restaurant أو steak_house.

تعرض واجهة برمجة التطبيقات تلقائيًا جميع الأماكن استنادًا إلى المَعلمة input، بغض النظر عن قيمة النوع الأساسي المرتبطة بالمكان. يمكنك حصر النتائج لتكون من نوع أساسي معيّن أو أنواع أساسية معيّنة من خلال تمرير المَعلمة types.

استخدِم هذه المَعلمة لتحديد ما يصل إلى خمس قيم من النوع من الجدول أ أو الجدول ب. يجب أن يتطابق مكان مع إحدى قيم النوع الأساسي المحدّدة ليتم تضمينها في الردّ.

يتم رفض الطلب مع ظهور خطأ INVALID_REQUEST في الحالات التالية:

  • تم تحديد أكثر من خمسة أنواع.
  • يتم تحديد أي أنواع غير معروفة.

على سبيل المثال، لحصر النتائج بالمتاجر التي تبيع السلع الرياضية، حدِّد هذا النوع في AutocompleteFilter:

حزمة تطوير البرامج (SDK) لأماكن Swift

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

Swift

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

Objective-C

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

البلدان

تضمين النتائج من قائمة المناطق المحدّدة فقط، والتي يتم تحديدها كصفيف يضم ما يصل إلى 15 قيمة من قيم نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد (ccTLD) ("نطاق المستوى الأعلى") التي تتألّف من حرفَين في حال حذف هذا الحقل، لن يتم تطبيق أي قيود على الردّ. على سبيل المثال، لتقتصر المناطق على ألمانيا وفرنسا:

حزمة تطوير البرامج (SDK) لأماكن Swift

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

Swift

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

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.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. بخلاف ذلك، لا يعرض الطلب أي نتائج.

على سبيل المثال:

حزمة تطوير البرامج (SDK) لأماكن Swift

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

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

المستطيل هو إطار عرض لخط العرض وخط الطول، ويتم تمثيله بنقطتَين 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، ولا يمكن أن يكون المربّع المعروض فارغًا. يؤدي استخدام مساحة عرض فارغة إلى حدوث خطأ.

على سبيل المثال، تحيط إطار العرض هذا بمدينة نيويورك بالكامل:

حزمة تطوير البرامج (SDK) لأماكن Swift

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

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

الأصل

نقطة المصدر التي يتم من خلالها احتساب المسافة المستقيمة إلى الوجهة (يتم عرضها على النحو التالي: distanceMeters). في حال حذف هذه القيمة، لن يتم عرض المسافة المستقيمة. يجب تحديدها على أنّها إحداثيات خط العرض وخط الطول:

حزمة تطوير البرامج (SDK) لأماكن Swift

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

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

regionCode

رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده على أنّه قيمة نطاق ccTLD ("نطاق الأولوية") تتألّف من حرفَين. تتطابق معظم رموز نطاقات المستوى الأعلى التي يتم ترميزها حسب البلد مع رموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز المستوى الأعلى للمنطقة المحدودة (ccTLD) في المملكة المتحدة هو "uk" (‎.co.uk)، بينما رمزه وفقًا لمعيار ISO 3166-1 هو "gb" (من الناحية الفنية للكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

إذا حدّدت رمز منطقة غير صالح، ستعرِض واجهة برمجة التطبيقات خطأ INVALID_ARGUMENT. يمكن أن تؤثّر المَعلمة في النتائج استنادًا إلى القانون الساري.

إضافة التطبيق المصغّر "الإكمال التلقائي للأماكن"

لتقديم تجربة اتّباع البيانات التلقائية للأماكن بشكلٍ متّسق بسهولة أكبر، يمكنك إضافة تطبيقات مصغّرة لميزة "اتّباع البيانات التلقائية للأماكن" إلى تطبيقك. توفّر التطبيقات المصغّرة واجهة مخصّصة بملء الشاشة تعالج إدخالات المستخدم وتعرض توقّعات الأماكن للمستخدم مع عرض عناصر AutocompletePlaceSuggestion على التطبيق. يمكنك بعد ذلك إرسال طلب تفاصيل الأماكن (جديد) للحصول على معلومات إضافية عن أيّ من توقّعات الأماكن.

widget للإكمال التلقائي للأماكن

مثلما هو الحال عند الحصول على اقتراحات الأماكن آليًا، تتيح لك الأداة المصغّرة "إكمال الأماكن تلقائيًا" استخدام رموز الجلسة لgrouped requests for autocompletion into session for billing purposes. يمكنك تمرير رمز مميّز للجلسة من خلال الاتصال AutocompleteSessionToken().

إذا لم تقدِّم رمز تعريف جلسة، ستنشئ الأداة مصغّرة رمز تعريف جلسة "الإكمال التلقائي"، والذي يمكن الحصول عليه بعد ذلك من دالة الاستدعاء onSelection. لمزيد من المعلومات عن استخدام الرموز المميّزة للجلسات، راجِع لمحة عن الرموز المميّزة للجلسات.

عند ضبط قيمة الربط show على true، سيتم نقل المستخدم إلى عرض ملء الشاشة حيث يمكنه اختيار مكان. بينما يكتب المستخدم، تعرِض الأداة المقترَحات للأماكن، مثل الأنشطة التجارية والعناوين ونقاط الجذب السياحي. عندما يختار المستخدم مكانًا، تستدعي الأداة معالج onSelection مع المكان الذي تم اختياره، وتغلق العرض بملء الشاشة.

مَعلمات التطبيق المصغّر "الإكمال التلقائي للأماكن"

بالإضافة إلى المَعلمات المتاحة برمجيًا، تقدّم الأداة المصغّرة "الإكمال التلقائي للأماكن" أيضًا المَعلمات التالية.

إظهار

يحدِّد show ما إذا كان سيتم عرض التطبيق المصغّر.

AutocompleteUICustomization

تحدّد مَعلمات AutocompleteUICustomization تخصيصات واجهة المستخدم التي سيتم تطبيقها على التطبيق المصغّر. في ما يلي خيارات customisation:

  • AutocompleteListDensity: تتيح لك هذه المَعلمة اختيار كثافة قائمة الاقتراحات، إما multiLine أو twoLine.
  • AutocompleteUIIcon: تتيح لك هذه المَعلمة اختيار ما إذا كنت تريد عرض الرمز التلقائي لكل عنصر من عناصر القائمة.

onSelection

يتم تنفيذ الإغلاق عند اختيار مكان.

onError

يتم تنفيذ الإغلاق عند حدوث خطأ. سيتمّ تمرير رمز PlacesError في حال حدوث خطأ.

اطّلِع على مثال كامل على الرمز.

أمثلة على ميزة "الإكمال التلقائي" (جديد)

استخدام locationRestriction وlocationBias

تستخدِم ميزة "الإكمال التلقائي (جديد)" الميل إلى استخدام عنوان IP تلقائيًا للتحكّم في منطقة البحث. من خلال منح الأولوية لعنوان IP، تستخدم واجهة برمجة التطبيقات عنوان IP للجهاز لمنح الأولوية للنتائج. يمكنك اختياريًا استخدام locationRestriction أو locationBias، ولكن ليس كِليهما، لتحديد منطقة للبحث.

يحدِّد قيد الموقع الجغرافي المنطقة التي تريد البحث فيها. ولا يتم عرض النتائج خارج المنطقة المحدّدة. يستخدم المثال التالي قيد الموقع الجغرافي لتقييد الطلب بقيد موقع جغرافي دائري بدائرة نصف قطرها 5,000 متر مع توسيع نطاق البحث حول القاهرة:

حزمة تطوير البرامج (SDK) لأماكن Swift

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

في حال تفعيل ميزة "الميل نحو الموقع الجغرافي"، يتم استخدام الموقع الجغرافي كعامل ميل، ما يعني أنّه يمكن عرض نتائج حول الموقع الجغرافي المحدّد، بما في ذلك النتائج خارج المنطقة المحدّدة. يغيّر المثال التالي الطلب السابق لاستخدام الميل إلى الموقع الجغرافي:

حزمة تطوير البرامج (SDK) لأماكن Swift

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

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

أنواع الاستخدام

استخدِم المَعلمة types لحصر النتائج من طلب معيّن على أنّها من نوع معيّن كما هو موضّح في الجدول أ والجدول ب. يمكنك تحديد صفيف يحتوي على ما يصل إلى خمس قيم. في حال حذفه، يتم عرض جميع الأنواع.

يحدِّد المثال التالي سلسلة طلب بحث هي "كرة القدم" ويستخدم المَعلمة types لحصر النتائج بالمنشآت من النوع "sporting_goods_store":

حزمة تطوير البرامج (SDK) لأماكن Swift

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

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

استخدام نقطة الانطلاق

عند تضمين المَعلمة origin في الطلب، المحدّدة على أنّها إحداثيات خطيّة للعرض والطول، تتضمّن واجهة برمجة التطبيقات المسافة المستقيمة من نقطة المصدر إلى الوجهة في الاستجابة. تعرض الإجابة القيمة للمسافة على أنّها distanceMeters.

يضبط هذا المثال نقطة الأصل على مركز مدينة سان فرانسيسكو:

حزمة تطوير البرامج (SDK) لأماكن Swift

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

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

إضافة تطبيق مصغّر لميزة "الإكمال التلقائي للأماكن"

حزمة تطوير البرامج (SDK) لأماكن Swift

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

عمليات تحديد المصدر

يمكنك استخدام ميزة "الإكمال التلقائي" (الميزة الجديدة) حتى بدون خريطة. إذا أردت عرض خريطة، يجب أن تكون خريطة Google. عند عرض اقتراحات من خدمة "الإكمال التلقائي (جديد)" بدون خريطة، يجب تضمين شعار Google معروضًا مضمّنًا في حقل البحث/النتائج. للحصول على مزيد من المعلومات، يُرجى الاطّلاع على مقالة عرض شعار Google و الإحالات.