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

تعرض خدمة "البحث النصي" (الجديدة) معلومات حول مجموعة من الأماكن استنادًا إلى سلسلة نصية (مثلاً، "بيتزا في نيويورك" أو "متاجر أحذية بالقرب من أوتاوا" أو "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 كائن يحدّد البحث.

  • اضبط سلسلة طلب البحث النصي على "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.DISPLAY_NAME);

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

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

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

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

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

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

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

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

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

    Place.Field.DISPLAY_NAME*
        * استخدِمها بدلاً من Place.Field.NAME (تم إيقافها نهائيًا في الإصدار 4.0).
    Place.Field.ID
Place.Field.RESOURCE_NAME*
        * يحتوي على اسم مورد المكان بالتنسيق: places/PLACE_ID.
         استخدِم DISPLAY_NAME للوصول إلى الاسم النصي للمكان.

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي Text Search Pro:

    Place.Field.ACCESSIBILITY_OPTIONS*
        استخدِم هذا الرمز بدلاً من Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (تم إيقافه نهائيًا).
    Place.Field.ADDRESS_COMPONENTS
Place.Field.ADR_FORMAT_ADDRESS
Place.Field.BUSINESS_STATUS
Place.Field.FORMATTED_ADDRESS*
        استخدِم هذا العمود بدلاً من Place.Field.ADDRESS (متوقّف نهائيًا).
    Place.Field.GOOGLE_MAPS_URI
Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL *
        استخدِم هذا الخيار بدلاً من Place.Field.ICON_URL (متوقّف نهائيًا).
    Place.Field.LOCATION*
        استخدِم هذا النوع بدلاً من Place.Field.LAT_LNG (تم إيقافه نهائيًا).
    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.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.USER_RATINGS_TOTAL، لأنّه لم يعُد متاحًا.
    Place.Field.WEBSITE_URI

  • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي الخاص بميزة "البحث النصي" في Enterprise Plus:

    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 (ترتيب النتائج حسب المسافة).
  • بالنسبة إلى طلب بحث غير مصنّف، مثل "ماونتن فيو، كاليفورنيا"، ننصحك بعدم ضبط مَعلمة ترتيب الأولوية.

  لضبط مَعلمة ترتيب الأولوية، استخدِم طريقة setRankPreference() عند إنشاء الكائن SearchByTextRequest.

• رمز المنطقة

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

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

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

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

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

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

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