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

اختيار النظام الأساسي: Android iOS JavaScript Web Service
المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

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

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

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

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

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

Places Swift SDK

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
}

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;
    }
  }
];

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

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

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

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

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

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

ردّ واحد (isOpenWithRequest)

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

اللغة القيمة إذا كانت مفتوحة القيمة في حال الإغلاق القيمة إذا كانت الحالة غير معروفة
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

الفوترة في isOpenWithRequest

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

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

Places Swift SDK

        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
        }

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
            }
          }];

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

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

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

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

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

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

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyName
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlaceID
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي لإصدار Nearby Search Enterprise:

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي لميزة "البحث القريب" في Enterprise Plus:

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

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

    Places Swift SDK

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

    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];

  • locationRestriction

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

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

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

  • includedTypes/excludedTypes, includedPrimaryTypes/excludedPrimaryTypes

    تتيح لك تحديد قائمة بأنواع من الجدول A المستخدَمة لفلترة نتائج البحث. يمكن تحديد ما يصل إلى 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"، ولكنها لن تعمل بشكل أساسي كـ "steak_house".

    includedTypes

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

    excludedTypes

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

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

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

    includedPrimaryTypes

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

    excludedPrimaryTypes

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

    إذا كانت هناك أي أنواع أساسية متعارضة، مثل نوع يظهر في كل من 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 على إشارات إلى المصدر وإشارات إلى المؤلف. إذا عرضت المراجعة في تطبيقك، عليك أيضًا عرض أي إشارة إلى المصدر أو المؤلف.

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