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

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

حزمة تطوير برامج الأماكن 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
}

ردود ميزة "بحث عن قرب"

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

Language القيمة إذا كانت مفتوحة القيمة في حال الإغلاق القيمة إذا كانت الحالة غير معروفة
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. يُعد إخفاء المجال ممارسة جيدة على التصميم لضمان عدم طلب بيانات غير ضرورية، مما يساعد على تجنب وقت المعالجة ورسوم الفوترة غير الضرورية.

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

    • تؤدي الحقول التالية إلى تشغيل رمز التخزين التعريفي للبحث عن الأجهزة المجاورة (الأساسي):

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

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

      GMSPlacePropertyCurrentOpeningHours, GMSPlacePropertySecondaryOpeningHours, GMSPlacePropertyPhoneNumber, GMSPlacePropertyPriceLevel، GMSPlacePropertyRating, GMSPlacePropertyOpeningHours, GMSPlacePropertyUserRatingsTotal, GMSPlacePropertyWebsite

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

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

    يجتاز المثال التالي قائمة من اثنين قيم الحقول لتحديد أن الكائن 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];

    حزمة تطوير برامج الأماكن 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 لتحديد المعلَمات الاختيارية البحث.

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

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

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

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

لمزيد من المعلومات، راجع الوثائق المتعلقة الإحالة.