البحث النصي (جديد)

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

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

الحصول على قائمة بالأماكن من خلال البحث النصي

يمكنك تقديم طلب بحث نصي من خلال استدعاء GMSPlacesClient searchByTextWithRequest:، مع تمرير عنصر GMSPlaceSearchByTextRequest الذي يحدّد مَعلمات الطلب وطريقة طلب إعادة الاتصال من النوع GMSPlaceSearchByTextResultCallback، لمعالجة الاستجابة.

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

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

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

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

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

let callback: GMSPlaceSearchByTextResultCallback = { [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().searchByText(with: request, callback: callback)

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

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

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

let restriction = RectangularLocationRestriction(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

ردود "البحث النصي"

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

الفوترة لحساب isOpenWithRequest

• يتم تحصيل رسوم حقلَي GMSPlacePropertyUTCOffsetMinutes وGMSPlacePropertyBusinessStatus ضمن رمز التخزين التعريفي للبيانات الأساسية. يتم تحصيل رسوم بقية ساعات العمل ضمن رمز التخزين التعريفي لـ "تفاصيل المكان (متقدّمة)".
• إذا كان GMSPlace العنصر يحتوي على هذه الحقول من طلب سابق، لن يتم تحصيل رسوم منك مرة أخرى.

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

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

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

          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
          }
          

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

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

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

  حدِّد سمات بيانات الأماكن التي تريد عرضها. نقْل قائمة بسمات GMSPlace التي تحدّد حقول البيانات المطلوب عرضها. في حال حذف قناع الحقل ، سيعرض الطلب خطأ.

  تُعدّ قوائم الحقول ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد في تجنُّب وقت المعالجة غير الضروري وتحميل رسوم الفوترة.

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

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

    GMSPlacePropertyPlaceID وGMSPlacePropertyName

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

    GMSPlacePropertyAddressComponents، GMSPlacePropertyBusinessStatus، GMSPlacePropertyFormattedAddress، GMSPlacePropertyIconBackgroundColor، GMSPlacePropertyIconImageURL، GMSPlacePropertyCoordinate، GMSPlacePropertyPhotos، 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

• textQuery

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

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

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

• includedType

  لحصر النتائج بالأماكن التي تتطابق مع النوع المحدّد في الجدول "أ" يمكن تحديد نوع واحد فقط. على سبيل المثال:

  • request.includedType = "bar"
  • request.includedType = "pharmacy"

• isOpenNow

  إذا كان الخيار true، يتم عرض الأماكن المفتوحة فقط في وقت إرسال الطلب. إذا كان الخيار false، أعرض جميع الأنشطة التجارية بغض النظر عن حالة الفتح. يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضبطت هذه المَعلمة على false.

• isStrictTypeFiltering

  تُستخدَم مع المَعلمة includeType. عند ضبطه على true، يتم عرض الأماكن التي تتطابق فقط مع الأنواع المحدّدة التي تم تحديدها باستخدام includeType. عندما يكون القيمة خطأ، وهو الإعداد التلقائي، يمكن أن يحتوي الردّ على أماكن لا تتطابق مع الأنواع المحدّدة.

• locationBias

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

  يمكنك تحديد locationRestriction أو locationBias، ولكن ليس كِليهما. يمكنك اعتبار locationRestriction محددًا للمنطقة التي يجب أن تظهر فيها النتائج، وlocationBias محددًا للمنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارج المنطقة.

  حدِّد المنطقة على أنّها إطار عرض مستطيل أو دائرة.

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

    request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

  • المستطيل هو إطار عرض لخطوط الطول والعرض، ويتم تمثيله بنقطة منخفضة ونقطة مرتفعة متعاكستين بشكل قطري. تشير النقطة المنخفضة إلى الزاوية الجنوبية الغربية من المستطيل، وتشير النقطة العالية إلى الزاوية الشمالية الشرقية من المستطيل.

    يُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يتضمّن حدوده. يجب أن تتراوح حدود خط العرض بين -90 و90 درجة، ويجب أن تتراوح حدود خط الطول بين -180 و180 درجة:

    • إذا كان low = high، يتألّف إطار العرض من تلك النقطة الواحدة.
    • إذا كان low.longitude > high.longitude، يتم قلب نطاق خط الطول (يمر إطار العرض بخط خط الطول الذي يبلغ 180 درجة).
    • إذا كانت القيمة low.longitude = -180 درجة و high.longitude = 180 درجة، يتضمّن إطار العرض جميع خطوط الطول.
    • إذا كان low.longitude = 180 درجة و high.longitude = -180 درجة، يكون نطاق خط الطول فارغًا.
    • إذا كان low.latitude > high.latitude، يكون نطاق خط العرض فارغًا.

• locationRestriction

  تُستخدَم لتحديد منطقة للبحث فيها. ولا يتم عرض نتائج خارج المنطقة المحدّدة. حدِّد المنطقة على أنّها إطار عرض مستطيل. اطّلِع على وصف locationBias للحصول على معلومات عن تحديد إطار العرض.

  يمكنك تحديد locationRestriction أو locationBias، ولكن ليس كِليهما. يمكنك اعتبار locationRestriction محددًا للمنطقة التي يجب أن تظهر فيها النتائج، وlocationBias محددًا للمنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارج المنطقة.

• maxResultCount

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

• minRating

  تحصر النتائج في التطبيقات التي يكون متوسّط تقييم المستخدمين لها أكبر من أو يساوي هذا الحدّ. يجب أن تتراوح القيم بين 0.0 و5.0 (بما في ذلك) وبصعد 0.5. على سبيل المثال: 0 و0.5 و1.0 و... و5.0 شاملة يتم تقريب القيم لأقرب 0.5. على سبيل المثال، تؤدي القيمة 0.6 إلى استبعاد كل النتائج التي يكون تقييمها أقل من 1.0.

• priceLevels

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

  حدِّد صفيفًا من قيمة واحدة أو أكثر من القيم المحدّدة باستخدام PriceLevel.

  على سبيل المثال:

  request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

• rankPreference

  تُحدِّد كيفية ترتيب النتائج في الردّ استنادًا إلى نوع طلب البحث:

  • بالنسبة إلى طلب بحث فئوي، مثل "مطاعم في مدينة دبي"، يكون الخيار .relevance (ترتيب النتائج حسب مدى صلة البحث) هو الإعداد التلقائي. يمكنك ضبط rankPreference على .relevance أو .distance (ترتيب النتائج حسب المسافة).
  • بالنسبة إلى طلب بحث غير فئوي، مثل "Mountain View, CA"، ننصح بعدم ضبط rankPreference.

• regionCode

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

  إذا كان اسم البلد في حقل العنوان في الاستجابة يتطابق مع رمز المنطقة، يتم حذف رمز البلد من العنوان.

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

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

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

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

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