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

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

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

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

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

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

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

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

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

    • تؤدي الحقول التالية إلى تفعيل بحث في الجوار 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

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

      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

    • تؤدي الحقول التالية إلى تفعيل بحث في الجوار Enterprise Plus SKU:

      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" ولكنها لا تعمل بشكل أساسي كـ "steak_house".

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

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

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

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

    أنواع الاستبعاد

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

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

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

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

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

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

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

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

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

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

    لضبط مَعلمة الأنواع الأساسية المستبعَدة، استدعِ الط0}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.