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

اختيار النظام الأساسي: Android iOS JavaScript Web Service

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

طلبات "البحث في الجوار" (جديد)

أرسِل طلبًا إلى Nearby Search (إصدار جديد) من خلال استدعاء 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، راجِع الوصول إلى حقول بيانات عنصر المكان.

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

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

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

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

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

    • تؤدي الحقول التالية إلى تشغيل Nearby Search Pro SKU:

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
          * استخدِمها بدلاً من Place.Field.NAME التي تم إيقافها نهائيًا.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * استخدِم هذا الرمز بدلاً من Place.Field.ICON_URL الذي تم إيقافه نهائيًا.
      Place.Field.ID
      Place.Field.LAT_LNG
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.RESOURCE_NAME
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT
      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • تؤدي الحقول التالية إلى تفعيل Nearby Search Enterprise SKU:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * استخدِم هذا الخيار بدلاً من Place.Field.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.USER_RATINGS_TOTAL، لأنّه متوقّف نهائيًا.
      Place.Field.WEBSITE_URI

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي الخاص بـ Nearby Search Enterprise Plus:

      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 لتحديد المَعلمات الاختيارية للبحث.

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

    تتيح لك تحديد قائمة بأنواع من الجدول A المستخدَمة لفلترة نتائج البحث. يمكن تحديد ما يصل إلى 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" ولكنّها لا تعمل بشكل أساسي كـ "steak_house".

    للاطّلاع على مثال حول كيفية استخدام includedTypes وexcludedTypes، راجِع طلبات "البحث القريب" (جديد).

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

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

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

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

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

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

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

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

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

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

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

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

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

    إذا كانت هناك أي أنواع أساسية متعارضة، مثل نوع يظهر في كل من 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، مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا بيانات المصدر المطلوبة.

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