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

اختيار النظام الأساسي: 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

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

      {2, 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.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.ALLOWS_DOGSPlace.Field.PARKING_OPTIONSPlace.Field.PAYMENT_OPTIONSPlace.Field.RESERVABLEPlace.Field.RESTROOMPlace.Field.REVIEWSPlace.Field.SERVES_BEERPlace.Field.SERVES_BREAKFASTPlace.Field.SERVES_BRUNCHPlace.Field.SERVES_COCKTAILSPlace.Field.SERVES_COFFEEPlace.Field.SERVES_DESSERTPlace.Field.SERVES_DINNERPlace.Field.SERVES_LUNCHPlace.Field.SERVES_VEGETARIAN_FOODPlace.Field.SERVES_WINEPlace.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". يتضمّن الردّ أماكن تتطابق مع واحد على الأقل من ال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، مثل الصور والمراجعات، يجب أن يعرض التطبيق أيضًا الإسنادات المطلوبة.

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