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

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

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

"4 شارع القدس، حدائق الأهرام، الجيزة" العديد من "هاي ستريت" في المملكة المتحدة، والعديد من "الشوارع الرئيسية" في الولايات المتحدة. لا يعرض طلب البحث النتائج المرغوبة ما لم يتم ضبط قيود على الموقع الجغرافي.
"مطعم سلسلة في دبي" عدة مواقع جغرافية لـ "مطاعم تابعة لسلسلة مطاعم" في نيويورك، بدون عنوان شارع أو حتى اسم شارع.
"4 شارع القدس، حدائق الأهرام، الجيزة" أو "4 شارع القدس، حدائق الأهرام" هناك اسم "هاي ستريت" واحد فقط في مدينة إيشر بالمملكة المتحدة، وشارع واحد فقط في مدينة "بليسانتون" في الولايات المتحدة.
"UniqueRestaurantName دبي" مؤسسة واحدة فقط تحمل هذا الاسم في نيويورك، ولا حاجة للتمييز بين عنوان الشارع
"مطاعم الكباب في دبي" يحتوي طلب البحث هذا على الموقع الجغرافي المفروض عليه، و "مطاعم البيتزا" هو نوع مكان محدد جيدًا. تعرض نتائج متعددة.
"+1 514-670-8700"

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

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

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

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

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

يشير نموذج طلب البحث النصي هذا إلى أنّ كائنات GMSPlace تحتوي على اسم المكان ومعرّف المكان لكل عنصر GMSPlace يظهر في نتائج البحث. كما أنه يقوم بتصفية الرد لإرجاع الأماكن من النوع "مطعم" فقط.

Swift

// 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)

Objective-C

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

GooglePlacesSwift

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 واحد لكل مكان مطابقة.

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

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

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

استخدِم الكائن 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، سيتم عرض جميع الأنشطة التجارية بغض النظر عن الحالة "مفتوح". في حال ضبط هذه المعلَمة على false، يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google".

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

عرض الإحالات في تطبيقك

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

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

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