البحث في الأماكن القريبة (ميزة جديدة)

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

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

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

طلبات "البحث عن مكان قريب" (جديد)

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

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

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

يحدّد مثال طلب البحث عن الأماكن القريبة هذا أنّ عناصر Place في الاستجابة повинна تحتوي على حقلَي المكان Place.Field.ID وPlace.Field.DISPLAY_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.DISPLAY_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، اطّلِع على الوصول إلى حقول بيانات 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.PRIMARY_TYPE، Place.Field.PRIMARY_TYPE_DISPLAY_NAME، 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.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS Place.Field.PRICE_LEVEL Place.Field.RATING Place.Field.SECONDARY_OPENING_HOURS Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI

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

      Place.Field.ALLOWS_DOGS، Place.Field.CURBSIDE_PICKUP، Place.Field.DELIVERY، Place.Field.DINE_IN، Place.Field.EDITORIAL_SUMMARY، Place.Field.EV_CHARGE_OPTIONS، Place.Field.FUEL_OPTIONS، Place.Field.GOOD_FOR_CHILDREN، Place.Field.GOOD_FOR_GROUPS، Place.Field.GOOD_FOR_WATCHING_SPORTS، Place.Field.LIVE_MUSIC، Place.Field.MENU_FOR_CHILDREN، Place.Field.OUTDOOR_SEATING، Place.Field.PARKING_OPTIONS، Place.Field.PAYMENT_OPTIONS، Place.Field.RESERVABLE، Place.Field.RESTROOM، Place.Field.REVIEWS، Place.Field.SERVES_BEER، Place.Field.SERVES_BREAKFAST، Place.Field.SERVES_BRUNCH، Place.Field.SERVES_COCKTAILS، Place.Field.SERVES_COFFEE، Place.Field.SERVES_DESSERT، 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.DISPLAY_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.DISPLAY_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 لفلترة النتائج في قائمة الأنواع المرتبطة بمكان معيّن.

    عند تحديد نوع أساسي عام، مثل "restaurant" أو "hotel"، يمكن أن يحتوي الردّ على أماكن ذات نوع أساسي أكثر تحديدًا من النوع المحدّد. على سبيل المثال، يمكنك تحديد تضمين نوع أساسي من "restaurant". يمكن أن يحتوي الردّ بعد ذلك على أماكن ذات نوع أساسي هو "restaurant"، ولكن يمكن أن يحتوي الردّ أيضًا على أماكن ذات نوع أساسي أكثر تحديدًا، مثل "chinese_restaurant" أو "seafood_restaurant".

    إذا تم تحديد عملية بحث مع قيود أنواع متعددة، لن يتم عرض سوى الأماكن التي تستوفي جميع القيود. على سبيل المثال، إذا حدّدت includedTypes = Arrays.asList("restaurant") وexcludedPrimaryTypes = Arrays.asList("steak_house")، يوفّر المكانان المعروضان خدمات ذات صلة"restaurant" ولكنهما لا يعملان primarily ك"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 المكوّن من حرفَين. لا تتوفّر قيمة تلقائية.

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

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

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

عرض الإسنادات في تطبيقك

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

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