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

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

GooglePlacesSwift

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
}

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

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

إلى جانب حقول البيانات، يحتوي الكائن GMSPlace في الاستجابة على دوال العضو التالية:

  • isOpen تحسب ما إذا كان المكان مفتوحًا في وقت معيّن.
  • وتحتسب isOpenAtDate ما إذا كان المكان مفتوحًا في تاريخ معيّن.

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

استخدِم الكائن 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];

    GooglePlacesSwift

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

  • locationRestriction

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

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

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

  • includeTypes/excludedTypes، وincludePrimaryTypes/excludedPrimaryTypes

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

    يمكن أن يكون للمكان نوع أساسي واحد من أنواع الجدول أ المرتبطة به. على سبيل المثال، قد يكون النوع الأساسي "mexican_restaurant" أو "steak_house". استخدِم includedPrimaryTypes وexcludedPrimaryTypes لفلترة النتائج على النوع الأساسي للمكان.

    يمكن أن يحتوي المكان أيضًا على قيم أنواع متعددة من أنواع الجدول أ المرتبط به. على سبيل المثال، قد يكون لمطعم الأنواع التالية: "seafood_restaurant" و"restaurant" و"food" و"point_of_interest" و"establishment". يمكنك استخدام includedTypes وexcludedTypes لفلترة النتائج على قائمة الأنواع المرتبطة بمكان معيّن.

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

لمزيد من المعلومات، اطّلِع على المستندات حول جهات تحديد المصدر.