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

اختيار النظام الأساسي: Android iOS JavaScript Web Service

المطوّرون في المنطقة الاقتصادية الأوروبية

إذا كان عنوان الفوترة الخاص بك يقع في المنطقة الاقتصادية الأوروبية، ستسري بنود خدمة "منصة خرائط Google" في المنطقة الاقتصادية الأوروبية على استخدامك للخدمات اعتبارًا من 8 تموز (يوليو) 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات

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

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

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

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

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

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

• الحصول على توقّعات الأماكن آليًا: يمكنك طلب البيانات من واجهة برمجة التطبيقات مباشرةً لاسترداد التوقّعات وعرضها في واجهة مستخدم مخصّصة.
• إضافة أداة Place Autocomplete: توفّر هذه الأداة تجربة إكمال تلقائي جاهزة للاستخدام تعرض عبارات مقترَحة أثناء كتابة المستخدم.

ملاحظة: لا تتوفّر أداة Autocomplete (New) إلا في الإصدار 10.0.0 والإصدارات الأحدث من Places Swift SDK لنظام التشغيل iOS. لمزيد من المعلومات، يُرجى الاطّلاع على Places Swift لنظام التشغيل iOS.

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

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

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

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

إصدار حزمة تطوير البرامج (SDK) في Swift الخاصة بخدمة "أماكن Google"

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

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

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

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

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

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

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

sessionToken

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

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

الأنواع

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

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

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

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

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

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

Places Swift SDK

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

Places Swift SDK

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، ستستخدم واجهة برمجة التطبيقات ميزة "تفضيل عناوين IP" تلقائيًا. باستخدام ميزة "تفضيل عناوين IP"، تستخدم واجهة برمجة التطبيقات عنوان IP الخاص بالجهاز لتفضيل النتائج.

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

• تحدّد السمة locationRestriction منطقة للبحث. لن يتم عرض نتائج خارج المنطقة المحدّدة.

حدِّد المنطقة locationBias أو locationRestriction كإطار عرض مستطيل أو كدائرة.

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

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

Places Swift SDK

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

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

Places Swift SDK

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). وفي حال حذف هذه القيمة، لن يتم عرض المسافة المستقيمة. يجب تحديدها كإحداثيات خطوط الطول والعرض:

Places Swift SDK

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 ("نطاق رفيع المستوى") مؤلّفة من حرفين. معظم رموز ccTLD مطابقة لرموز ISO 3166-1، مع بعض الاستثناءات البارزة. على سبيل المثال، رمز ccTLD الخاص بالمملكة المتحدة هو "uk" (‎.co.uk)، بينما رمز ISO 3166-1 الخاص بها هو "gb" (وهو يشير تقنيًا إلى كيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية").

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

shouldIncludePureServiceAreaBusinesses

إذا كانت القيمة true، تعرض الأنشطة التجارية لمنطقة الخدمة فقط في مصفوفة الردّ. المؤسسة ضمن منطقة الخدمة هي مؤسسة تقدّم خدماتها من خلال الانتقال إلى المواقع الجغرافية للعملاء أو توصيل الخدمة إليهم مباشرةً، ولكنّها لا تقدّم خدماتها لهم في عنوانها.

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

Places Swift SDK

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Swift

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Objective-C

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

إضافة أداة الإكمال التلقائي للأماكن

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

ملاحظة: لا تتوفّر الأداة Autocomplete (New) إلا في الإصدار 10.0.0 والإصدارات الأحدث من Places Swift SDK لنظام التشغيل iOS. لمزيد من المعلومات، يُرجى الاطّلاع على Places Swift لنظام التشغيل iOS.

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

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

ملاحظة: استخدام رموز الجلسات اختياري، ولكن ننصح به.

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

مَعلمات أداة "الإكمال التلقائي للأماكن"

بالإضافة إلى المَعلمات المتاحة برمجيًا، تقدّم أداة Place Autocomplete أيضًا المَعلمات التالية.

إظهار

تحدِّد السمة show ما إذا كان سيتم عرض الأداة.

AutocompleteUICustomization

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

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

onSelection

الدالة التي سيتم تنفيذها عند اختيار مكان.

onError

الدالة البرمجية التي سيتم تنفيذها عند حدوث خطأ. سيتم تمرير PlacesError في حال حدوث خطأ.

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

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

استخدام locationRestriction وlocationBias

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

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

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

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

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

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

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":

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

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.

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

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

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

إضافة أداة "الإكمال التلقائي للأماكن"

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