طلب البحث عن قرب (جديد) يستخدم كإدخال المنطقة للبحث المحدد كدائرة، يحددها إحداثيات خط العرض وخط الطول للنقطة المركزية للدائرة ونصف القطر بالمتر. يعرض الطلب قائمة بالأماكن المطابقة، التي يمثّل كل منها عنصر
GMSPlace
، ضمن منطقة البحث المحدّدة.
بشكل تلقائي، يحتوي الردّ على أماكن من جميع الأنواع داخل منطقة البحث. يمكنك فلترة الرد اختياريًا عن طريق تحديد قائمة بأنواع الأماكن لتضمينها بشكل صريح في الرد أو استبعادها منها. على سبيل المثال، يمكنك تضمين الأماكن التي تكون من النوع "مطعم" و"مخبز" و "مقهى" فقط في الرد، أو استبعاد جميع الأماكن من النوع "مدرسة".
طلبات البحث عن قرب (جديدة)
يمكنك تقديم طلب "بحث عن قرب" من خلال استدعاء GMSPlacesClient searchNearbyWithRequest:
،
وتمرير عنصر
GMSPlaceSearchNearbyRequest
يحدد معلمات الطلب وطريقة لرد الاتصال، من النوع
GMSPlaceSearchNearbyResultCallback
،
للتعامل مع الاستجابة.
يحدّد الكائن GMSPlaceSearchNearbyRequest
جميع المعلَمات
المطلوبة والاختيارية
للطلب. تشمل المَعلمات المطلوبة ما يلي:
- قائمة الحقول المطلوب عرضها في الكائن
GMSPlace
، وتسمى أيضًا قناع الحقل، كما هو محدّد فيGMSPlaceProperty
. إذا لم تحدّد حقلاً واحدًا على الأقل في قائمة الحقول، أو إذا حذفت قائمة الحقول، سيعرض الطلب رسالة خطأ. - القيود المفروضة على الموقع الجغرافي، أي الدائرة التي تحدّد منطقة البحث.
يشير هذا المثال لطلب البحث عن أماكن قريبة إلى أنّ كائنات GMSPlace
تحتوي على اسم المكان (GMSPlacePropertyName
) وإحداثيات المكان (GMSPlacePropertyCoordinate
) لكل عنصر GMSPlace
يظهر في نتائج البحث. كما أنه يقوم بتصفية الرد لإرجاع الأماكن من النوع "مطعم" و "مقهى" فقط.
Swift
// Array to hold the places in the response var placeResults: [GMSPlace] = [] // Define the search area as a 500 meter diameter circle in San Francisco, CA. let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500) // Specify the fields to return in the GMSPlace object for each place in the response. let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue} // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties) let includedTypes = ["restaurant", "cafe"] request.includedTypes = includedTypes let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } placeResults = results } GMSPlacesClient.shared().searchNearby(with: request, callback: callback)
Objective-C
// Array to hold the places in the response _placeResults = [NSArray array]; // Define the search area as a 500 meter diameter circle in San Francisco, CA. id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500); // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc] initWithLocationRestriction:circularLocation placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]]; // Set the place types to filter on. NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ]; request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes]; [_placesClient searchNearbyWithRequest:request callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { // Get list of places. _placeResults = places; } } ];
GooglePlacesSwift
let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500) let searchNearbyRequest = SearchNearbyRequest( locationRestriction: restriction, placeProperties: [ .name, .coordinate], includedTypes: [ .restaurant, .cafe ], ) switch await placesClient.searchNearby(with: searchNearbyRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
الردود على ميزة "البحث عن قرب"
تعرض واجهة برمجة تطبيقات Google Search API مصفوفة من التطابقات في شكل عناصرGMSPlace
، مع عنصر GMSPlace
واحد لكل مكان مطابق.
إلى جانب حقول البيانات، يحتوي الكائن GMSPlace
في
الاستجابة على دوال العضو التالية:
-
isOpen
تحسب ما إذا كان المكان مفتوحًا في وقت معيّن. - وتحتسب
isOpenAtDate
ما إذا كان المكان مفتوحًا في تاريخ معيّن.
المعلمات المطلوبة
استخدِم الكائن GMSPlaceSearchNearbyRequest
لتحديد المعلمات المطلوبة للبحث.
-
قائمة الحقول
عندما تطلب تفاصيل المكان، عليك تحديد البيانات المراد عرضها في الكائن
GMSPlace
للمكان كقناع حقل. لتحديد قناع الحقل، مرِّر مصفوفة من القيم منGMSPlaceProperty
إلى الكائنGMSPlaceSearchNearbyRequest
. إخفاء الحقول هو ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد على تجنُّب وقت المعالجة غير الضروري ورسوم الفوترة.حدِّد واحدًا أو أكثر من الحقول التالية:
تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث عن قرب (الأساسي):
GMSPlacePropertyAddressComponents
،GMSPlacePropertyBusinessStatus
،GMSPlacePropertyCoordinate
،GMSPlacePropertyFormattedAddress
،GMSPlacePropertyName
،GMSPlacePropertyIconBackgroundColor
،GMSPlacePropertyIconImageURL
،GMSPlacePropertyPhotos
،GMSPlacePropertyPlaceID
،GMSPlacePropertyPlusCode
،GMSPlacePropertyTypes
،GMSPlacePropertyUTCOffsetMinutes
،GMSPlacePropertyViewport
،GMSPlacePropertyWheelchairAccessibleEntrance
تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث عن قرب (متقدم):
GMSPlacePropertyCurrentOpeningHours
،GMSPlacePropertySecondaryOpeningHours
،GMSPlacePropertyPhoneNumber
،GMSPlacePropertyPriceLevel
،GMSPlacePropertyRating
،GMSPlacePropertyOpeningHours
،GMSPlacePropertyUserRatingsTotal
،GMSPlacePropertyWebsite
تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي لميزة "البحث عن قرب" (المُفضَّل):
GMSPlacePropertyCurbsidePickup
،GMSPlacePropertyDelivery
،GMSPlacePropertyDineIn
،GMSPlacePropertyEditorialSummary
،GMSPlacePropertyReservable
،GMSPlacePropertyReviews
،GMSPlacePropertyServesBeer
،GMSPlacePropertyServesBreakfast
،GMSPlacePropertyServesBrunch
،GMSPlacePropertyServesDinner
،GMSPlacePropertyServesLunch
،GMSPlacePropertyServesVegetarianFood
،GMSPlacePropertyServesWine
،GMSPlacePropertyTakeout
يمرِّر المثال التالي قائمة من قيمتَي حقل للإشارة إلى أنّ عنصر
GMSPlace
الذي يعرضه الطلب يحتوي على الحقلَينname
وplaceID
:Swift
// Specify the place data types to return. let fields: [GMSPlaceProperty] = [.placeID, .name]
Objective-C
// Specify the place data types to return. NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
GooglePlacesSwift
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
-
locationRestriction
عنصر
GMSPlaceLocationRestriction
يحدد المنطقة المطلوب البحث عنها كدائرة، ويتم تحديدها بواسطة نقطة المركز ونصف القطر بالمتر. يجب أن يتراوح النطاق الجغرافي بين 0.0 و50000.0، بشكل شامل. النطاق التلقائي هو 0.0. يجب عليك ضبطه في طلبك على قيمة أكبر من 0.0.
المعلمات الاختيارية
استخدِم الكائن GMSPlaceSearchNearbyRequest
لتحديد المعلمات الاختيارية للبحث.
-
includeTypes/excludedTypes، وincludePrimaryTypes/excludedPrimaryTypes
تتيح لك هذه الميزة تحديد قائمة بأنواع من أنواع الجدول أ المستخدَم لفلترة نتائج البحث. ويمكن تحديد ما يصل إلى 50 نوعًا في كل فئة من فئات القيود المفروضة على الأنواع.
يمكن أن يكون للمكان نوع أساسي واحد من أنواع الجدول أ المرتبطة به. على سبيل المثال، قد يكون النوع الأساسي
"mexican_restaurant"
أو"steak_house"
. استخدِمincludedPrimaryTypes
وexcludedPrimaryTypes
لفلترة النتائج على النوع الأساسي للمكان.يمكن أن يحتوي المكان أيضًا على قيم أنواع متعددة من أنواع الجدول أ المرتبط به. على سبيل المثال، قد يكون لمطعم الأنواع التالية:
"seafood_restaurant"
و"restaurant"
و"food"
و"point_of_interest"
و"establishment"
. يمكنك استخدامincludedTypes
وexcludedTypes
لفلترة النتائج على قائمة الأنواع المرتبطة بمكان معيّن.إذا تم تحديد عملية بحث باستخدام عدة قيود على الأنواع، لن يتم عرض سوى الأماكن التي تستوفي جميع هذه القيود. على سبيل المثال، إذا حدّدت
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
، تقدّم الأماكن التي تم إرجاعها خدمات"restaurant"
ذات الصلة، ولكنها لا تعمل بشكل أساسي باعتبارها"steak_house"
.includedTypes
قائمة بأنواع الأماكن من الجدول أ للبحث عنها. إذا تم حذف هذه المَعلمة، يتم عرض الأماكن من جميع الأنواع.
excludedTypes
قائمة بأنواع الأماكن من الجدول أ المطلوب استبعادها من عملية البحث.
إذا حدّدت كلاً من
includedTypes
(مثل"school"
) والexcludedTypes
(مثل"primary_school"
) في الطلب، سيشمل الرد أماكن يتم تصنيفها على أنّها"school"
وليس"primary_school"
. يتضمن الرد أماكن تتطابق مع مكان واحد على الأقل منincludedTypes
ولا شيء منexcludedTypes
.في حال وجود أي أنواع متعارضة، مثل ظهور نوع معيّن في كل من
includedTypes
وexcludedTypes
، يتم عرض الخطأINVALID_REQUEST
.includedPrimaryTypes
قائمة بأنواع الأماكن الأساسية من الجدول أ لتضمينها في عملية بحث.
excludedPrimaryTypes
قائمة بأنواع الأماكن الأساسية من الجدول أ المطلوب استبعادها من البحث.
وفي حال وجود أي أنواع أساسية متعارضة، مثل ظهور نوع معيّن في كل من
includedPrimaryTypes
وexcludedPrimaryTypes
، يتم عرض الخطأINVALID_ARGUMENT
. -
maxResultCount
تحدّد هذه السمة الحد الأقصى لعدد نتائج الأماكن المطلوب عرضها. ويجب أن تتراوح القيمة بين 1 و20 (الخيار التلقائي).
-
rankPreference
تمثّل هذه السمة نوع الترتيب المطلوب استخدامه. إذا تم حذف هذه المَعلمة، يتم ترتيب النتائج حسب مدى رواجها. يمكن أن يكون أحد الأنواع التالية:
.popularity
(الخيار التلقائي) لترتيب النتائج استنادًا إلى مدى رواجها.- يتيح لك الخيار
.distance
ترتيب النتائج تصاعديًا حسب بُعدها عن الموقع الجغرافي المحدّد.
-
regionCode
تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الردّ، ويتم تحديده كقيمة لرمز CLDR مكوَّن من حرفين. لا تتوفّر قيمة تلقائية.
وإذا كان اسم البلد في الحقل
formattedAddress
في الردّ يتطابق معregionCode
، سيتم حذف رمز البلد منformattedAddress
. ليس لهذه المَعلمة أي تأثير علىadrFormatAddress
، الذي يتضمّن دائمًا اسم البلد، أو علىshortFormattedAddress
الذي لا يتضمّنه مطلقًا.وتكون معظم رموز CLDR متطابقة مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.
عرض الإحالات في تطبيقك
عندما يعرض تطبيقك معلومات تم الحصول عليها من
GMSPlacesClient
،
مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا الإحالات المطلوبة.
على سبيل المثال، تحتوي السمة reviews
للكائن GMSPlacesClient
على مصفوفة تضم ما يصل إلى خمسة عناصر من GMSPlaceReview
. يمكن أن يحتوي كل عنصر GMSPlaceReview
على عمليات تحديد المصدر وذِكر أسماء المؤلفين.
إذا عرضت المراجعة في تطبيقك، عليك أيضًا عرض أي معلومات عن مصدر أو اسم مؤلف.
لمزيد من المعلومات، اطّلِع على المستندات حول جهات تحديد المصدر.