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

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

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

" 10 High Street, UK" أو "123 Main Street, US" عدة "شوارع رئيسية" في المملكة المتحدة، والعديد من "الشوارع الرئيسية" في الولايات المتحدة لا يعرض طلب البحث نتائج مرغوبة ما لم يتم ضبط قيود على الموقع الجغرافي.
"سلسلة مطاعم نيويورك" تتوفّر عدة مواقع جغرافية لـ "سلسلة مطاعم" في نيويورك، ولا يتم تقديم عنوان شارع أو حتى اسم شارع.
"10 High Street, Escher UK" أو "123 Main Street, Pleasanton US" شارع "هاي ستريت" واحد فقط في مدينة إيشر بالمملكة المتحدة، و "شارع رئيسي" واحد فقط في مدينة بليسانتون بولاية كاليفورنيا الأمريكية
"UniqueRestaurantName في نيويورك" مؤسسة واحدة فقط بهذا الاسم في دبي، ولا حاجة إلى التفريق بين عنوان الشارع.
"مطاعم البيتزا في دبي" يتضمّن طلب البحث هذا القيود المفروضة على الموقع الجغرافي، ويُعدّ "مطاعم البيتزا" نوعًا محدّدًا من الأماكن. ويؤدي إلى إرجاع نتائج متعددة.
"+1 514-670-8700"

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

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

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

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

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

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

Swift

// Create the GMSPlaceSearchByTextRequest object.
let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID];
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
request.locationRestriction = GMSPlaceRectangularLocationOption(
      CLLocationCoordinate2D(latitude: 20, longitude: 30),
      CLLocationCoordinate2D(latitude: 40, longitude: 50)
)

// Array to hold the places in the response
placeResults = [];

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
  }
  self.placeResults = results
}

GMSPlacesClient.shared().searchByTextWithRequest(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.locationRestriction = GMSPlaceRectangularLocationOption(
    CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50));
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.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 (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، عليك عرض جميع الأنشطة التجارية بغض النظر عن الحالة "مفتوح". يتم عرض الأماكن التي لا تحدد ساعات العمل في قاعدة بيانات "أماكن Google" إذا ضبطت هذه المعلمة على false.

  • isStrictTypeFiltering

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

  • locationBias

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

    يمكنك تحديد السمة locationRestriction أو السمة locationBias، ولكن ليس كليهما. يمكنك اعتبار السمة locationRestriction على أنّها تحدّد المنطقة التي يجب أن تكون النتائج ضمنها والسمة locationBias تحدّد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارج المنطقة.

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

    • يتم تحديد الدائرة بنقطة المركز ونصف القطر بالمتر. ويجب أن يتراوح النطاق الجغرافي بين 0.0 و50000.0 بشكل شامل. نصف القطر الافتراضي هو 0.0. مثلاً:

      request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.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 على السمات وسمات المؤلف. إذا عرضت المراجعة في تطبيقك، عليك أيضًا عرض أي إحالة أو إحالة للمؤلف.

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