يتم استخدام طلب بحث قريب (جديد) كإدخال للمنطقة التي يتم البحث فيها
محددة كدائرة محددة من خلال إحداثيات خط العرض وخط الطول للنقطة المركزية
الدائرة ونصف القطر بالمتر. يعرض الطلب قائمة بالأماكن المطابقة، ويتم تمثيل كل منها بعلامة
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 }
ردود ميزة "بحث عن قرب"
تعرض واجهة برمجة تطبيقات البحث القريب مصفوفة من النتائج المطابقة على شكل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
لفلترة النتائج على قائمة الأنواع المرتبطة مكان.عندما تحدد نوعًا أساسيًا عامًا، مثل
"restaurant"
أو"hotel"
، يمكن أن يحتوي الرد على أماكن من نوع أساسي أكثر تحديدًا من المحدد. على سبيل المثال، يمكنك تحديد تضمين نوع أساسي من"restaurant"
يمكن أن يحتوي الرد بعد ذلك على أماكن من النوع الأساسي"restaurant"
، ولكن يمكن أن يحتوي الردّ أيضًا على أماكن ذات وصف أكثر تحديدًا النوع الأساسي، مثل"chinese_restaurant"
أو"seafood_restaurant"
.إذا تم تحديد عملية بحث مع قيود أنواع متعددة، يتم فقط تحديد الأماكن التي تفي بجميع القيود يتم إرجاعها. على سبيل المثال، إذا حددت
{"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
على السمات وسمات المؤلف.
إذا عرضت المراجعة في تطبيقك، يجب أيضًا عرض أي مصدر أو مؤلف.
الإحالة.
لمزيد من المعلومات، راجع الوثائق المتعلقة الإحالة.