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

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

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

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

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

يكون طلب البحث عن نص على النحو التالي:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_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.DISPLAY_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.DISPLAY_NAME);

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

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

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

في ما يلي المَعلمات المطلوبة لسمة SearchByTextRequest:

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

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

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

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

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

    Place.Field.DISPLAY_NAME، Place.Field.ID، Place.Field.RESOURCE_NAME
    

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

    Place.Field.ACCESSIBILITY_OPTIONS، Place.Field.ADDRESS_COMPONENTS، Place.Field.ADR_FORMAT_ADDRESS، Place.Field.BUSINESS_STATUS، Place.Field.FORMATTED_ADDRESS، Place.Field.GOOGLE_MAPS_URI، Place.Field.ICON_BACKGROUND_COLOR، Place.Field.ICON_MASK_URL، Place.Field.LOCATION، Place.Field.PHOTO_METADATAS، Place.Field.PLUS_CODE، Place.Field.PRIMARY_TYPE، Place.Field.PRIMARY_TYPE_DISPLAY_NAME، Place.Field.SHORT_FORMATTED_ADDRESS، Place.Field.SUB_DESTINATIONS، Place.Field.TYPES، Place.Field.UTC_OFFSET، Place.Field.VIEWPORT
    

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

    Place.Field.CURRENT_OPENING_HOURS، Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER، Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS، Place.Field.PRICE_LEVEL، Place.Field.RATING، Place.Field.SECONDARY_OPENING_HOURS، Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    

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

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

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

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

• فلترة الأنواع الصارمة

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

  لضبط مَعلمة الفلترة حسب النوع الصارم، استخدِم طريقة setStrictTypeFiltering() عند إنشاء عنصر SearchByTextRequest.