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

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

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

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

إجراء طلب بحث عن الأجهزة المجاورة (جديد) من خلال الاتصال PlacesClient.searchNearby، SearchNearbyRequest يحدد معلمات الطلب.

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

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

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

// 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 لفلترة النتائج على قائمة الأنواع المرتبطة مكان.

  عند تحديد نوع أساسي عام، مثل "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 مؤلف من حرفين. لا يوجد قيمة افتراضية.

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

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

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

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

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

لمزيدٍ من المعلومات، يُرجى الاطلاع على سياسات حزمة تطوير البرامج للأماكن بشأن Android