البحث عن قرب (جديد)

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

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

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

طلبات البحث عن الأجهزة المجاورة (الجديدة)

يمكنك إجراء طلب "بحث عن قرب" (جديد) من خلال استدعاء PlacesClient.searchNearby، وتمرير كائن SearchNearbyRequest يحدّد معلَمات الطلب.

يحدّد الكائن SearchNearbyRequest جميع المعلمات المطلوبة والاختيارية للطلب. وتشمل المَعلمات المطلوبة ما يلي:

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

يوضّح مثال طلب البحث القريب هذا أن كائنات Place للاستجابة تحتوي على حقلَي المكان Place.Field.ID وPlace.Field.NAME لكل عنصر Place في نتائج البحث. كما أنها تقوم بتصفية الاستجابة فقط لإرجاع الأماكن من نوع "مطعم" و "مقهى"، ولكن تستبعد الأماكن من نوع "مطعم_البيتزا" و "مطعم_أمريكا".

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

ردود البحث عن الأجهزة المجاورة (الجديدة)

تمثّل الفئة SearchNearbyResponse الاستجابة لطلب بحث. يحتوي كائن SearchNearbyResponse على:

  • قائمة تضم عناصر Place تمثل جميع الأماكن المطابقة، مع إضافة عنصر Place واحد لكل مكان مطابق.
  • يحتوي كل عنصر Place فقط على الحقول المحدّدة من خلال قائمة الحقول التي تم ضبطها في الطلب.

على سبيل المثال، في الطلب، حدَّدت قائمة حقول على النحو التالي: 

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

تعني قائمة الحقول هذه أنّ كل عنصر Place في الردّ يحتوي فقط على رقم تعريف المكان واسم كل مكان مطابق. يمكنك بعد ذلك استخدام الطريقتين Place.getId() وPlace.getName() للوصول إلى هذه الحقول في كل كائن Place.

للاطّلاع على مزيد من الأمثلة على الوصول إلى البيانات في عنصر Place، يُرجى الاطّلاع على الوصول إلى حقول بيانات عنصر المكان.

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

استخدِم الكائن SearchNearbyRequest لتحديد المعلَمات المطلوبة للبحث.

  • قائمة الحقول

    عند طلب تفاصيل مكان، عليك تحديد البيانات المطلوب عرضها في الكائن Place للمكان كقناع حقل. لتحديد قناع الحقل، مرِّر مصفوفة من القيم من Place.Field إلى الكائن SearchNearbyRequest. يُعد الإخفاء الميداني ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، مما يساعد على تجنب وقت المعالجة ورسوم الفوترة غير الضرورية.

    حدِّد حقلاً واحدًا أو أكثر من الحقول التالية:

    • تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث عن الأجهزة المجاورة (الأساسي):

      Place.Field.ADDRESS_COMPONENTS، Place.Field.BUSINESS_STATUS، Place.Field.ADDRESS، Place.Field.ICON_BACKGROUND_COLOR، Place.Field.ICON_URL، Place.Field.LAT_LNG، Place.Field.PHOTO_METADATAS، Place.Field.PLUS_CODE، Place.Field.ID، Place.Field.NAME، Place.Field.TYPES، Place.Field.UTC_OFFSET، Place.Field.VIEWPORT، Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث عن قرب (متقدم):

      Place.Field.CURRENT_OPENING_HOURS، Place.Field.SECONDARY_OPENING_HOURS، Place.Field.PHONE_NUMBER، Place.Field.PRICE_LEVEL، Place.Field.RATING، Place.Field.OPENING_HOURS، Place.Field.USER_RATINGS_TOTAL، Place.Field.WEBSITE_URI

    • تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث عن قرب (المُفضَّل):

      Place.Field.CURBSIDE_PICKUP، Place.Field.DELIVERY، Place.Field.DINE_IN، Place.Field.EDITORIAL_SUMMARY، Place.Field.RESERVABLE، Place.Field.REVIEWS، Place.Field.SERVES_BEER، Place.Field.SERVES_BREAKFAST، Place.Field.SERVES_BRUNCH، Place.Field.SERVES_DINNER، Place.Field.SERVES_LUNCH، Place.Field.SERVES_VEGETARIAN_FOOD، Place.Field.SERVES_WINE، Place.Field.TAKEOUT

    لضبط مَعلمة قائمة الحقول، يمكنك طلب الطريقة setPlaceFields() عند إنشاء كائن SearchNearbyRequest.

    يحدّد المثال التالي قائمة من قيمتَي حقل لتحديد أنّ العنصر Place الذي يعرضه طلب يحتوي على الحقلَين Place.Field.ID وPlace.Field.NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

  • القيود المفروضة على الموقع الجغرافي

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

    لضبط مَعلمة تقييد الموقع الجغرافي، يمكنك استدعاء الطريقة setLocationRestriction() عند إنشاء كائن SearchNearbyRequest.

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

استخدِم الكائن SearchNearbyRequest لتحديد المعلَمات الاختيارية للبحث.

  • الأنواع والأنواع الأساسية

    تتيح لك هذه السمة تحديد قائمة بالأنواع من أنواع الجدول أ المستخدمة لفلترة نتائج البحث. يمكن تحديد ما يصل إلى 50 نوعًا في كل فئة من فئات القيود.

    لا يمكن أن يحتوي المكان إلا على نوع أساسي واحد من أنواع الجدول أ المرتبطة به. على سبيل المثال، قد يكون النوع الأساسي "mexican_restaurant" أو "steak_house". استخدِم includedPrimaryTypes وexcludedPrimaryTypes لفلترة النتائج حسب النوع الأساسي للمكان.

    يمكن أن يحتوي المكان أيضًا على قيم أنواع متعددة من أنواع الجدول أ المرتبطة به. على سبيل المثال، قد يتميّز مطعم بالأنواع التالية: "seafood_restaurant" و"restaurant" و"food" و"point_of_interest" و"establishment". استخدِم includedTypes وexcludedTypes لفلترة النتائج حسب قائمة الأنواع المرتبطة بأحد الأماكن.

    في حال تحديد عملية بحث مع أنواع متعددة من القيود، لن يتم عرض سوى الأماكن التي تستوفي جميع القيود. على سبيل المثال، إذا حددت includedTypes = Arrays.asList("restaurant") وexcludedPrimaryTypes = Arrays.asList("steak_house")، تقدّم الأماكن المعروضة خدمات ذات صلة بـ "restaurant"، ولكنها لا تعمل بشكل أساسي كـ "steak_house".

    للاطّلاع على مثال حول كيفية استخدام includedTypes وexcludedTypes، يُرجى الاطّلاع على طلبات البحث عن الأجهزة المجاورة (الجديدة).

    الأنواع المضمّنة

    قائمة بأنواع الأماكن من الجدول أ للبحث عنها. وفي حال حذف هذه المَعلمة، يتم عرض الأماكن بجميع أنواعها.

    لضبط مَعلمة الأنواع المُضمنة، يمكنك طلب الطريقة setIncludedTypes() عند إنشاء عنصر SearchNearbyRequest.

    الأنواع المستبعَدة

    قائمة بأنواع الأماكن من الجدول أ لاستبعادها من عملية بحث.

    إذا حدّدت كلاً من includedTypes (مثل "school") وexcludedTypes (مثل "primary_school") في الطلب، سيتضمّن الردّ أماكن مصنّفة على أنّها "school" وليس "primary_school". يتضمّن الردّ أماكن تطابق عنصرًا واحدًا على الأقل من includedTypes ولا شيء من excludedTypes.

    إذا كان هناك أي أنواع متضاربة، كظهور أحد الأنواع في كل من includedTypes وexcludedTypes، سيتم عرض الخطأ INVALID_REQUEST.

    لضبط مَعلمة الأنواع المُستبعَدة، يمكنك طلب الطريقة setExcludedTypes() عند إنشاء كائن SearchNearbyRequest.

    الأنواع الأساسية المضمّنة

    قائمة بأنواع الأماكن الأساسية من الجدول أ لتضمينها في البحث.

    لضبط مَعلمة الأنواع الأساسية المضمَّنة، يجب طلب الطريقة setIncludedPrimaryTypes() عند إنشاء عنصر SearchNearbyRequest.

    الأنواع الأساسية المستبعدة

    قائمة بأنواع الأماكن الأساسية من الجدول أ لاستبعادها من عملية بحث.

    إذا كان هناك أي أنواع أساسية متعارضة، مثل ظهور أحد الأنواع في كل من includedPrimaryTypes وexcludedPrimaryTypes، سيتم عرض الخطأ INVALID_ARGUMENT.

    لضبط مَعلمة الأنواع الأساسية المستبعدة، يمكنك طلب الطريقة setExcludedPrimaryTypes() عند إنشاء عنصر SearchNearbyRequest.

  • الحد الأقصى لعدد النتائج

    لتحديد الحد الأقصى لعدد نتائج الأماكن المطلوب عرضها. ويجب أن تتراوح القيمة بين 1 و20 (القيمة التلقائية).

    لضبط مَعلمة الحد الأقصى لعدد النتائج، يمكنك طلب الطريقة setMaxResultCount() عند إنشاء كائن SearchNearbyRequest.

  • الترتيب المفضّل

    نوع الترتيب المطلوب استخدامه. في حال إسقاط هذه المَعلمة، يتم ترتيب النتائج حسب مدى رواجها. قد يكون واحدًا مما يلي:

    • "POPULARITY" (الخيار التلقائي) يساعد في ترتيب النتائج استنادًا إلى مدى رواجها.
    • DISTANCE يؤدي الترتيب إلى ترتيب تصاعدي حسب المسافة من الموقع الجغرافي المحدد.

    لضبط مَعلمة الترتيب المفضّلة، يجب طلب الطريقة setRankPreference() عند إنشاء كائن SearchNearbyRequest.

  • رمز المنطقة

    تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده كقيمة رمز CLDR مؤلف من حرفَين. لا يوجد قيمة افتراضية.

    إذا كان اسم البلد في الحقل formattedAddress في الردّ يتطابق مع regionCode، سيتم حذف رمز البلد من formattedAddress.

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

    لضبط مَعلمة رمز المنطقة، يجب طلب الطريقة setRegionCode() عند إنشاء عنصر SearchNearbyRequest.

عرض عمليات تحديد المصدر في تطبيقك

عندما يعرض تطبيقك معلومات تم الحصول عليها من PlacesClient، مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا سمات المساهمين المطلوبة.

لمزيدٍ من المعلومات، يُرجى الاطّلاع على حزمة تطوير البرامج (SDK) الخاصة بسياسات الأماكن لنظام التشغيل Android.