يعرض البحث النصي معلومات حول مجموعة من الأماكن استنادًا إلى سلسلة - على سبيل المثال: "بيتزا في دبي" أو "متاجر أحذية بالقرب من أوتاوا" أو "123 الشارع الرئيسي". تستجيب الخدمة بقائمة من الأماكن التي تطابق السلسلة النصية وأي تحيز للموقع تم تعيينه.
تفيد هذه الخدمة بشكل خاص في إجراء طلبات بحث غامضة عن العناوين في نظام آلي، وقد تتطابق المكونات التي لا تتضمّن عناوين في السلسلة مع الأنشطة التجارية والعناوين أيضًا. ومن الأمثلة على طلبات البحث عن العناوين الغامضة العناوين ذات التنسيق السيئ أو الطلبات التي تتضمّن مكونات غير مرتبطة بالعناوين، مثل أسماء الأنشطة التجارية. قد تؤدي الطلبات مثل أول مثالين إلى عرض نتائج صفرية ما لم يتم تحديد موقع جغرافي - مثل المنطقة أو القيود المفروضة على الموقع الجغرافي أو انحياز الموقع الجغرافي.
| "4 شارع القدس، حدائق الأهرام، الجيزة" | العديد من "هاي ستريت" في المملكة المتحدة، والعديد من "الشوارع الرئيسية" في الولايات المتحدة. لا يعرض طلب البحث النتائج المرغوبة ما لم يتم ضبط قيود على الموقع الجغرافي. |
| "مطعم مطاعم دبي" | عدة مواقع جغرافية لـ "ChainRestaurant" في نيويورك، بدون عنوان شارع أو حتى اسم شارع. |
| "4 شارع القدس، حدائق الأهرام، الجيزة" أو "4 شارع القدس، حدائق الأهرام" | هناك اسم "هاي ستريت" واحد فقط في مدينة إيشر بالمملكة المتحدة، وشارع واحد فقط في مدينة "بليسانتون" في الولايات المتحدة. |
| "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يحدد البحث.اضبط سلسلة طلب البحث النصي على "الطعام النباتي الحار".
اضبط الحد الأقصى لعدد أماكن النتائج على 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، يُرجى الاطّلاع على المقالة
الوصول إلى حقول بيانات عناصر المكان.
المعلمات المطلوبة
-
قائمة الحقول
حدِّد حقول بيانات الأماكن التي تريد عرضها. مرِّر قائمة من قيم
Place.Fieldتحدّد حقول البيانات المطلوب عرضها. ولا تتوفّر قائمة تلقائية للحقول المعروضة في الاستجابة.قوائم الحقول هي ممارسة تصميم جيدة لضمان عدم طلب بيانات غير ضرورية، ما يساعد على تجنُّب وقت المعالجة غير الضروري ورسوم الفوترة.
حدِّد واحدًا أو أكثر من الحقول التالية:
تؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث النصي (المعرّف فقط):
Place.Field.IDوPlace.Field.NAMEتؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث النصي (الأساسي):
Place.Field.ADDRESS_COMPONENTS،Place.Field.BUSINESS_STATUS،Place.Field.ADDRESS،Place.Field.ICON_BACKGROUND_COLOR،Place.Field.ICON_URL،Place.Field.LAT_LNG،Place.Field.PHOTO_METADATAS،Place.Field.PLUS_CODE،Place.Field.TYPES،Place.Field.UTC_OFFSET،Place.Field.VIEWPORT،Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCEتؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث النصي (متقدم):
Place.Field.CURRENT_OPENING_HOURS،Place.Field.SECONDARY_OPENING_HOURS،Place.Field.PHONE_NUMBER،Place.Field.PRICE_LEVEL،Place.Field.RATING،Place.Field.OPENING_HOURS،Place.Field.USER_RATINGS_TOTAL،Place.Field.WEBSITE_URIتؤدي الحقول التالية إلى ظهور رمز التخزين التعريفي للبحث النصي (مُفضَّل):
Place.Field.CURBSIDE_PICKUP،Place.Field.DELIVERY،Place.Field.DINE_IN،Place.Field.EDITORIAL_SUMMARY،Place.Field.RESERVABLE،Place.Field.REVIEWS،Place.Field.SERVES_BEER،Place.Field.SERVES_BREAKFAST،Place.Field.SERVES_BRUNCH،Place.Field.SERVES_DINNER،Place.Field.SERVES_LUNCH،Place.Field.SERVES_VEGETARIAN_FOOD،Place.Field.SERVES_WINE،Place.Field.TAKEOUT
-
طلب بحث نصي
السلسلة النصية المطلوب البحث عليها، على سبيل المثال: "مطعم" أو "123 الشارع الرئيسي" أو "أفضل مكان للزيارة في دبي". تعرض واجهة برمجة التطبيقات النتائج المطابِقة المرشحة استنادًا إلى هذه السلسلة، وترتِّب النتائج استنادًا إلى مدى صلتها بالموضوع الذي يتم رصده.
المعلمات الاختيارية
يمكنك ضبط هذه المعلمات باستخدام طرق SearchByTextRequest.Builder. على سبيل المثال، لضبط الحد الأقصى لعدد النتائج، يمكنك استدعاء الدالة SearchByTextRequest.Builder.setMaxResultCount().
النوع المضمَّن
تقتصر النتائج على الأماكن المطابقة للنوع المحدّد والمحدّد في الجدول أ. يمكن تحديد نوع واحد فقط. مثال:
setIncludedType("bar")setIncludedType("pharmacy")
انحياز الموقع الجغرافي
لتحديد منطقة للبحث. يمثّل هذا الموقع الجغرافي انحيازًا، أي أنّه يمكن عرض نتائج حول الموقع الجغرافي المحدّد، بما في ذلك النتائج خارج المنطقة المحدّدة.
ويمكنك تحديد القيود المفروضة على الموقع الجغرافي أو تحديد الانحياز في الموقع الجغرافي، ولكن لا يمكنك تحديد الاثنين معًا. يمكن اعتبار القيود المفروضة على الموقع الجغرافي على أنّه تحديد المنطقة التي يجب أن تظهر فيها النتائج، والانحياز حسب الموقع الجغرافي على أنّه يحدد المنطقة التي يجب أن تكون النتائج قريبة منها ولكن يمكن أن تكون خارجها.
حدِّد المنطقة على أنّها إطار عرض مستطيل أو كدائرة.
يتم تحديد الدائرة من خلال نقطة المركز ونصف القطر بالمتر. ويجب أن يتراوح النطاق الجغرافي بين 0.0 و50000.0، بشكل شامل. النطاق الجغرافي الافتراضي هو 0.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، يكون نطاق خط العرض فارغًا.
يجب تعبئة كل من الحقلين المنخفض والمرتفعين، ولا يمكن أن يكون المربّع الممثل فارغًا. يؤدي إطار العرض الفارغ إلى حدوث خطأ.
على سبيل المثال، في إطار العرض المستطيل، يمكنك الاطّلاع على طلبات البحث النصي.
- إذا كانت
قيد الموقع
لتحديد منطقة للبحث. ولن يتم عرض النتائج خارج المنطقة المحدّدة. حدِّد المنطقة على أنّها إطار عرض مستطيل. راجِع وصف انحياز الموقع الجغرافي للحصول على معلومات عن تحديد إطار العرض.
ويمكنك تحديد القيود المفروضة على الموقع الجغرافي أو تحديد الانحياز في الموقع الجغرافي، ولكن لا يمكنك تحديد الاثنين معًا. يمكن اعتبار القيود المفروضة على الموقع الجغرافي على أنّه تحديد المنطقة التي يجب أن تظهر فيها النتائج، والانحياز حسب الموقع الجغرافي على أنّه يحدد المنطقة التي يجب أن تكون النتائج قريبة منها ولكنّها قد تكون خارج المنطقة.
-
الحد الأقصى لعدد النتائج
تحدّد هذه السمة الحد الأقصى لعدد نتائج الأماكن المطلوب عرضها. ويجب أن تتراوح القيمة بين 1 و20 (الخيار التلقائي).
الحد الأدنى للتقييم
يحصر خيار النتائج فقط المستخدمين الذين يزيد متوسط تقييمهم عن الحدّ الأقصى المسموح به أو مساويًا له. يجب أن تتراوح القيم بين 0.0 و5.0 (شاملةً) بزيادات 0.5. على سبيل المثال: 0، 0.5، 1.0، ... ، 5.0 بشكل شامل. ويتم تقريب القيم إلى أقرب 0.5. على سبيل المثال، تؤدي القيمة 0.6 إلى إزالة جميع النتائج ذات التقييم الأقل من 1.0.
مفتوح الآن
إذا كانت السمة
true، يجب عرض الأماكن المفتوحة للنشاط التجاري فقط في وقت إرسال طلب البحث. إذا تم عرضfalse، سيتم عرض جميع الأنشطة التجارية بغض النظر عن الحالة "مفتوح". في حال ضبط هذه المعلَمة علىfalse، يتم عرض الأماكن التي لا تحدّد ساعات العمل في قاعدة بيانات "أماكن Google".-
مستويات الأسعار
حصر عملية البحث على الأماكن التي تم وضع علامة عليها بمستويات أسعار معيّنة. يكون الخيار التلقائي هو اختيار جميع مستويات السعر.
حدِّد قائمة بقيمة واحدة أو أكثر من قيم الأعداد الصحيحة التالية:
- من 1 إلى
PRICE_LEVEL_INEXPENSIVE - 2 -
PRICE_LEVEL_MODERATE - من 3 إلى
PRICE_LEVEL_EXPENSIVE - من 4 إلى
PRICE_LEVEL_VERY_EXPENSIVE
- من 1 إلى
الترتيب المفضّل
تحدِّد هذه السمة كيفية ترتيب النتائج في الردّ. تستخدم واجهة برمجة التطبيقات
RELEVANCEتلقائيًا إذا كان ذلك منطبقًا. على سبيل المثال، إذا كان طلب البحث مثل "مطاعم في مدينة نيويورك"، يكونRELEVANCEهو الخيار التلقائي. بالنسبة إلى طلبات البحث الجغرافية، مثل "Mountain View, CA" أو أي نوع آخر من طلبات البحث، لا يتم تطبيق خيار تلقائي وستظهر النتائج بالترتيب الذي تعرضه الخلفية.وتتضمّن القيم ما يلي:
SearchByTextRequest.RankPreference.DISTANCE: ترتيب النتائج حسب المسافةSearchByTextRequest.RankPreference.RELEVANCE: ترتيب النتائج حسب مدى صلتها بموضوع البحث
رمز المنطقة
تمثّل هذه السمة رمز المنطقة المستخدَم لتنسيق الردّ، ويتم تحديده كقيمة لرمز CLDR مكوَّن من حرفين. ويمكن أن يكون لهذه المَعلمة أيضًا تأثير متحيز في نتائج البحث. لا تتوفّر قيمة تلقائية.
إذا كان اسم البلد في حقل العنوان في الردّ يتطابق مع رمز المنطقة، سيتم حذف رمز البلد من العنوان.
تتطابق معظم رموز CLDR مع رموز ISO 3166-1، مع بعض الاستثناءات الملحوظة. على سبيل المثال، نطاق المستوى الأعلى الذي يتم ترميزه حسب البلد (ccTLD) في المملكة المتحدة هو "uk" (.co.uk)، في حين أنّ رمز ISO 3166-1 هو "gb" (من الناحية الفنية لكيان "المملكة المتحدة لبريطانيا العظمى وأيرلندا الشمالية"). يمكن أن تؤثر المَعلمة في النتائج استنادًا إلى القانون الساري.
فلترة الأنواع الصارمة
تُستخدَم مع المَعلمة include type. عند ضبط السياسة على
true، لن يتم عرض سوى الأماكن التي تتطابق مع الأنواع المحدّدة التي يحدّدها نوع التضمين. عندما يكون استخدامfalseهو السمة التلقائية، قد يتضمّن الردّ أماكن لا تتطابق مع الأنواع المحدّدة.