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

اختيار النظام الأساسي: Android iOS JavaScript خدمة الويب

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

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

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

يمكنك تقديم طلب بحث عن الأماكن المجاورة من خلال استدعاء دالة GMSPlacesClient searchNearbyWithRequest:، مع تمرير عنصر GMSPlaceSearchNearbyRequest يحدّد مَعلمات الطلب وطريقة طلب معاودة الاتصال، من النوع GMSPlaceSearchNearbyResultCallback، لمعالجة الاستجابة.

يحدِّد عنصر GMSPlaceSearchNearbyRequest جميع المَعلمات المطلوبة والاختيارية للطلب. تشمل المَعلمات المطلوبة ما يلي:

  • قائمة الحقول التي سيتم عرضها في كائن GMSPlace، وتُعرف أيضًا باسم قناع الحقل، على النحو المحدّد من قِبل GMSPlaceProperty. إذا لم تحدِّد حقلًا واحدًا على الأقل في قائمة الحقول، أو إذا حذفت قائمة الحقول، سيعرض الطلب خطأ.
  • قيود الموقع الجغرافي، أي الدائرة التي تحدّد منطقة البحث

يحدّد مثال طلب البحث عن الأماكن القريبة أنّ عناصر GMSPlace في الاستجابة повинна تحتوي على اسم المكان (GMSPlacePropertyName) وتنسيقات المكان (GMSPlacePropertyCoordinate) لكل عنصر GMSPlace في نتائج البحث. ويفلتر أيضًا الاستجابة لعرض الأماكن من النوع "مطعم" و "مقهى" فقط.

Swift

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

Objective-C

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

حزمة تطوير البرامج (SDK) لأماكن Swift لنظام التشغيل iOS (إصدار تجريبي)

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

الردود على ميزة "بحث في الجوار"

تُعرِض Nearby Search API مصفوفة من المطابقات في شكل عناصر GMSPlace ، مع عنصر GMSPlace واحد لكل مكان مطابق.

الحصول على حالة "مفتوح"

يحتوي عنصر GMSPlacesClient على دالة عضوية تُسمى isOpenWithRequest (isOpenRequest في Swift وisPlaceOpenRequest في GooglePlacesSwift) تعرض استجابة تشير إلى ما إذا كان المكان مفتوحًا حاليًا استنادًا إلى الوقت المحدّد في الطلب.

تأخذ هذه الطريقة وسيطة واحدة من النوع GMSPlaceIsOpenWithRequest تحتوي على ما يلي:

  • عنصر GMSPlace أو سلسلة تحدّد معرّف مكان لمزيد من المعلومات عن إنشاء عنصر "مكان" باستخدام الحقول اللازمة، يُرجى الاطّلاع على تفاصيل المكان.
  • عنصر اختياري من النوع NSDate (Obj-C) أو Date (Swift) يحدِّد الوقت الذي تريد التحقّق منه إذا لم يتم تحديد وقت، يكون الإعداد التلقائي هو الآن.
  • طريقة GMSPlaceOpenStatusResponseCallback لمعالجة الاستجابة
    • >

تتطلّب طريقة GMSPlaceIsOpenWithRequest ضبط الحقول التالية في كائن GMSPlace:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

إذا لم يتم توفير هذه الحقول في عنصر "الموقع الجغرافي"، أو إذا تم ضبط معرّف مكان، تستخدم الطريقة GMSPlacesClient GMSFetchPlaceRequest: لجلبها.

ردّ واحد (isOpenWithRequest)

تعرض isOpenWithRequest عنصر GMSPlaceIsOpenResponse يحتوي على قيمة منطقية باسم status تشير إلى ما إذا كان النشاط التجاري مفتوحًا أو مغلقًا أو إذا كانت الحالة غير معروفة.

اللغة القيمة في حال كانت مفتوحة القيمة في حال الإغلاق القيمة في حال كانت الحالة غير معروفة
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift (إصدار تجريبي) true false nil

الفوترة لـ isOpenWithRequest

مثال: تقديم طلب GMSPlaceIsOpenWithRequest

يوضّح المثال التالي كيفية إعداد GMSPlaceIsOpenWithRequest داخل عنصر GMSPlace حالي.

Swift

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }

Objective-C

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];

          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }

            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];

GooglePlacesSwift

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }

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

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

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

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

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

    يُرسِل المثال التالي قائمة بوحدتَي قيمة حقل لتحديد أنّ عنصر GMSPlace الذي يعرضه الطلب يحتوي على الحقلَين name وplaceID:

    Swift

    // Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]

    Objective-C

    // Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];

    حزمة تطوير البرامج (SDK) لأماكن Swift لنظام التشغيل iOS (إصدار تجريبي)

    // Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]

  • locationRestriction

    عنصر GMSPlaceLocationRestriction الذي يحدِّد المنطقة التي يتم البحث فيها على أنّها دائرة، ويتم تحديدها من خلال نقطة المركز ونصف القطر بالمتر يجب أن يتراوح نصف القطر بين 0.0 و50000.0، بما في ذلك هذين الرقمَين. شعاع الدائرة التلقائي هو 0.0. يجب ضبطها في طلبك على قيمة أكبر من 0.0.

المعلمات الاختيارية

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

  • includedTypes/excludedTypes، وincludedPrimaryTypes/excludedPrimaryTypes

    يتيح لك تحديد قائمة بالأنواع من الأنواع في الجدول "أ" المستخدَمة لفلترة نتائج البحث. يمكن تحديد ما يصل إلى 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": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}، يوفّر المكان المعروض خدمات ذات صلة"restaurant"، ولكنّه لا يعمل primarily ك"steak_house".

    includedTypes

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

    excludedTypes

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

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

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

    includedPrimaryTypes

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

    excludedPrimaryTypes

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

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

  • maxResultCount

    تُستخدَم لتحديد الحد الأقصى لعدد نتائج الأماكن التي سيتم عرضها. يجب أن تتراوح القيمة بين 1 و20 (القيمة التلقائية) بما في ذلك الرقمان.

  • rankPreference

    نوع الترتيب المراد استخدامه في حال حذف هذه المَعلمة، يتم ترتيب النتائج حسب مدى الرواج. يمكن أن يكون أحد العناصر التالية:

    • .popularity (تلقائي) لترتيب النتائج حسب مدى شيوعها
    • .distance لترتيب النتائج تصاعديًا حسب المسافة من الموقع الجغرافي المحدّد

  • regionCode

    رمز المنطقة المستخدَم لتنسيق الاستجابة، ويتم تحديده على أنّه قيمة رمز CLDR المكوّن من حرفَين. لا تتوفّر قيمة تلقائية.

    إذا كان اسم البلد في حقل formattedAddress في الاستجابة يتطابق مع regionCode، يتم حذف رمز البلد من formattedAddress. لا تؤثر هذه المَعلمة في adrFormatAddress التي تتضمّن دائمًا اسم البلد، أو في shortFormattedAddress التي لا تتضمّن هذا الاسم مطلقًا.

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

عرض الإسنادات في تطبيقك

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

على سبيل المثال، تحتوي السمة reviews للكائن GMSPlacesClient على صفيف يصل إلى خمسة كائنات GMSPlaceReview. يمكن أن يحتوي كل عنصر GMSPlaceReview على إحالات واقتباسات للمؤلف. إذا عرضت المراجعة في تطبيقك، يجب أيضًا عرض أيّ مصدر أو مصدر للمؤلف.

لمزيد من المعلومات، يُرجى الاطّلاع على المستندات المتعلّقة بموضوع الإحالات.