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

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

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

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

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

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

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

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

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

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

Swift

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

Objective-C

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

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

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

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

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

query

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

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

الأنواع

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

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

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

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

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

البلدان

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

Swift

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

Objective-C

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

GooglePlacesSwift

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

إذا حدّدت كلاً من locationRestriction وcountries، سيتم عرض النتائج في منطقة تقاطع الإعدادَين.

inputOffset

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

تحيز الموقع أو locationRestriction

يمكنك تحديد locationBias أو locationRestriction، ولكن ليس كليهما، لتحديد منطقة البحث. يمكنك اعتبار السمة locationRestriction بمثابة تحديد المنطقة التي يجب أن تكون النتائج ضمنها وlocationBias تحديد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارجها.

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

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

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

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

مثلاً:

Swift

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

GooglePlacesSwift

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله كنقطتين مواجهتين قطريًا لنقطتين low وhigh. يُعد إطار العرض منطقة مغلقة، مما يعني أنه يتضمن حدوده. يجب أن تتراوح حدود خطوط العرض ما بين -90 و90 درجة ضمنًا، ويجب أن تتراوح حدود خط الطول بين -180 و180 درجة ضمنًا:

  • إذا كانت low = high، يتكوّن إطار العرض من هذه النقطة الفردية.
  • إذا كانت low.longitude > high.longitude، يتم قلب نطاق خط الطول (يتجاوز إطار العرض خط الطول 180 درجة).
  • إذا كانت low.longitude = -180 درجة وhigh.longitude= 180 درجة، يشمل إطار العرض جميع خطوط الطول.
  • إذا كانت low.longitude = 180 درجة وhigh.longitude = -180 درجة، سيكون نطاق خط الطول فارغًا.

يجب ملء كل من low وhigh، ولا يمكن أن يكون المربّع الممثَّل فارغًا. يؤدي استخدام إطار عرض فارغ إلى حدوث خطأ.

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

Swift

let high = CLLocationCoordinate2DMake(40.477398, -74.259087)
let low = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

Objective-C

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

GooglePlacesSwift

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

الأصل

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

Swift

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

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];

GooglePlacesSwift

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

regionCode

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

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

sessionToken

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

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

استخدام حصر الموقع الجغرافي وانحياز المواقع الجغرافية

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

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

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

Objective-C


CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

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

Swift

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

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

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

يحدّد المثال التالي سلسلة طلب بحث "كرة القدم" ويستخدم مَعلمة الأنواع لحصر النتائج بمؤسسات من النوع "sporting_goods_store":

Swift

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
    
let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

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

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
    

استخدام المصدر

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

يحدّد هذا المثال الأصل في وسط سان فرانسيسكو:

Swift

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin
    
let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective-C


GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

GooglePlacesSwift

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

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

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