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

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

بالنسبة إلى مطوّري البرامج في المنطقة الاقتصادية الأوروبية (EEA)

إذا كان عنوان إرسال الفواتير في المنطقة الاقتصادية الأوروبية، ستسري "بنود خدمة منصة خرائط Google في المنطقة الاقتصادية الأوروبية" على استخدامك للخدمات اعتبارًا من 8 يوليو 2025. تختلف الوظائف حسب المنطقة. مزيد من المعلومات.

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

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

ملاحظة: يتوفّر "بحث في الجوار (جديد)" في Places SDK لنظام التشغيل Android الإصدار 3.5.0 والإصدارات الأحدث. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة اختيار إصدار حزمة تطوير البرامج (SDK). لمزيد من المعلومات حول استخدام واجهات برمجة تطبيقات Kotlin التي تمت إضافتها في الإصدار 4.0.0، يُرجى الاطّلاع على النظرة العامة على المرجع.

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

يمكنك إجراء طلب "بحث في الجوار (جديد)" من خلال استدعاء 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();
    });

ملاحظة: لمزيد من المعلومات حول تهيئة PlacesClient، يُرجى الاطّلاع على تهيئة عميل Places API.

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

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

تمثّل فئة 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.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 وincludedPrimaryTypes وexcludedPrimaryTypes من الطلب، يعرض البحث أماكن من جميع الأنواع ضمن حدود قيود الموقع الجغرافي.

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

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

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

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

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