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

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

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

يتشابه البحث النصي (جديد) مع البحث عن قرب (جديد). والفرق الرئيسي بين الاثنين هو أن البحث النصي (جديد) يتيح لك تحديد سلسلة بحث عشوائية، في حين أن البحث عن قرب (جديد) يتطلب منطقة محددة للبحث فيها.

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

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

طلبات البحث النصي

يكون طلب البحث النصي بالشكل:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

في هذا المثال:

  • يمكنك ضبط قائمة الحقول لتتضمن Place.Field.ID وPlace.Field.NAME فقط. وهذا يعني أنّ عناصر Place في الردّ التي تمثّل كل مكان مطابق لا تحتوي إلا على هذين الحقلَين.

  • استخدِم SearchByTextRequest.Builder لإنشاء كائن SearchByTextRequest يحدّد البحث.

    • اضبط سلسلة طلب البحث النصي على "Spicy Vegetarian Food".

    • اضبط الحد الأقصى لعدد أماكن النتائج على 10. الإعداد التلقائي والحدّ الأقصى هو 20

    • حصر منطقة البحث على المستطيل المحدد من خلال إحداثيات خطوط الطول والعرض. لا يتم عرض أي نتائج مطابقة خارج هذه المنطقة.

  • أضِف OnSuccessListener واحصل على الأماكن المطابقة من الكائن SearchByTextResponse.

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

تمثّل الفئة SearchByTextResponse الاستجابة لطلب بحث. يحتوي كائن SearchByTextResponse على:

  • قائمة تضم عناصر Place تمثل جميع الأماكن المطابقة، مع إضافة عنصر Place واحد لكل مكان مطابق.

  • يحتوي كل عنصر Place فقط على الحقول المحدّدة من خلال قائمة الحقول التي تم تمريرها في الطلب.

على سبيل المثال، في الطلب، حدَّدت قائمة حقول على النحو التالي:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

تعني قائمة الحقول هذه أنّ كل عنصر Place في الردّ يحتوي فقط على رقم تعريف المكان واسم كل مكان مطابق. يمكنك بعد ذلك استخدام الطريقتين Place.getId() وPlace.getName() للوصول إلى هذه الحقول في كل كائن Place.

للاطّلاع على مزيد من الأمثلة على الوصول إلى البيانات في عنصر Place، يُرجى الاطّلاع على الوصول إلى حقول بيانات عنصر المكان

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

المعلمات المطلوبة لـ SearchByTextRequest هي:

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

    حدِّد حقول بيانات الأماكن التي تريد عرضها. مرِّر قائمة بقيم Place.Field لتحديد حقول البيانات المطلوب عرضها. لا تتوفر قائمة تلقائية للحقول التي تم إرجاعها في الردّ.

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

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

    لضبط مَعلمة قائمة الحقول، يمكنك طلب الطريقة setPlaceFields() عند إنشاء العنصر SearchByTextRequest.

  • طلب بحث نصي

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

    لضبط معلَمة طلب البحث النصي، يمكنك طلب الطريقة setTextQuery() عند إنشاء كائن SearchByTextRequest.

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

استخدِم الكائن SearchByTextRequest لتحديد المَعلمات الاختيارية لطلبك.

  • النوع المضمَّن

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

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

    لضبط مَعلمة النوع المضمّنة، يمكنك طلب الطريقة setIncludedType() عند إنشاء عنصر SearchByTextRequest.

  • تحيز الموقع

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

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

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

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

      // Define latitude and longitude coordinates of the center of the search area.
LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);

// Use the builder to create a SearchByTextRequest object.
// Set the radius of the search area to 500.0 meters.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();

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

      يُعدّ إطار العرض منطقة مغلقة، ما يعني أنّه يتضمّن حدوده. يجب أن تتراوح حدود خطوط العرض بين -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، سيكون نطاق خط العرض فارغًا.

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

      على سبيل المثال، يمكنك الاطّلاع على طلبات البحث النصي على إطار عرض مستطيل.

      لضبط مَعلمة انحياز الموقع الجغرافي، يمكنك طلب الطريقة setLocationBias() عند إنشاء عنصر SearchByTextRequest.

  • القيود المفروضة على الموقع الجغرافي

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

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

    لضبط مَعلمة تقييد الموقع الجغرافي، يمكنك طلب الطريقة setLocationRestriction() عند إنشاء عنصر SearchByTextRequest.

  • الحد الأقصى لعدد النتائج

    لتحديد الحد الأقصى لعدد نتائج الأماكن المطلوب عرضها. ويجب أن تتراوح القيمة بين 1 و20 (القيمة التلقائية).

    لضبط مَعلمة الحد الأقصى لعدد النتائج، يمكنك طلب الطريقة setMaxResultCount() عند إنشاء كائن SearchByTextRequest.

  • الحد الأدنى للتقييم

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

    لضبط الحدّ الأدنى لمَعلمة التقييم، يمكنك طلب الطريقة setMinRating() عند إنشاء العنصر SearchByTextRequest.

  • مفتوح الآن

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

    لضبط المَعلمة open الآن، يمكنك طلب الطريقة setOpenNow() عند إنشاء الكائن SearchByTextRequest.

  • مستويات الأسعار

    تتضمّن النتائج تلقائيًا الأماكن التي تقدّم خدمات بجميع مستويات الأسعار. لحصر النتائج لتشمل فقط الأماكن بمستويات أسعار معيّنة، يمكنك ضبط قائمة من القيم الصحيحة التي تتوافق مع مستويات الأسعار للأماكن التي تريد عرضها:

    • 1 - يقدم المكان خدمات غير مكلفة.
    • 2 - يقدّم المكان خدمات بأسعار معتدلة.
    • 3 - المكان يقدم خدمات باهظة الثمن.
    • 4 - يقدم المكان خدمات باهظة الثمن.

    لضبط مَعلمة مستويات السعر، يمكنك طلب الطريقة setPriceLevels() عند إنشاء عنصر SearchByTextRequest.

  • الترتيب المفضّل

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

    • بالنسبة إلى طلب بحث فئوي مثل "مطاعم في دبي"، يكون SearchByTextRequest.RankPreference.RELEVANCE (ترتيب النتائج حسب مدى صلة البحث بالموضوع) هو الإعداد التلقائي. يمكنك ضبط الترتيب المفضّل على SearchByTextRequest.RankPreference.RELEVANCE أو SearchByTextRequest.RankPreference.DISTANCE (ترتيب النتائج حسب المسافة).
    • بالنسبة إلى طلب البحث غير الفئوي، مثل "Mountain View, CA"، ننصحك بترك معلَمة الترتيب المفضّلة بدون ضبط.

    لضبط مَعلمة الترتيب المفضّلة، يجب طلب الطريقة setRankPreference() عند إنشاء كائن SearchByTextRequest.

  • رمز المنطقة

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

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

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

    لضبط مَعلمة رمز المنطقة، يجب طلب الطريقة setRegionCode() عند إنشاء عنصر SearchByTextRequest.

  • تصفية متشددة للأنواع

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

    لضبط مَعلمة فلترة النوع المتشدد، يمكنك طلب الطريقة setStrictTypeFiltering() عند إنشاء كائن SearchByTextRequest.