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

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

بالإضافة إلى المَعلمات المطلوبة، تتيح خدمة "البحث النصي (جديد)" تحسين طلبات البحث باستخدام المَعلمات الاختيارية للحصول على نتائج أفضل.

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

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

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

// 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، يُرجى مراجعة الوصول إلى حقول بيانات عنصر المكان.

تقسيم النتائج على عدّة صفحات

يوفّر صف SearchByTextResponse في Text Search إمكانية الوصول إلى تقسيم نتائج البحث النصي إلى صفحات من خلال الطريقة getPagination()، التي تعرض عنصر Pagination.

استخدِم طريقة hasNextPage() في عنصر "تقسيم النتائج على صفحات" لتحديد ما إذا كانت هناك صفحات إضافية من النتائج متاحة. تُرجع هذه الطريقة قيمة منطقية (صحيح أو خطأ).

بينما تعرض hasNextPage() القيمة "صحيح"، استدعِ الطريقة fetchNextPage() لاسترداد الصفحة التالية من النتائج.

يوضّح المثال التالي كيفية التحقّق ممّا إذا كانت صفحة تالية متاحة، ثم تحميل الصفحة.

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

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

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

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

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

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

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

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

    Place.Field.DISPLAY_NAME*
        * Use instead of Place.Field.NAME (deprecated in version 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.

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

  The text string on which to search, for example: "restaurant", "123 Main Street", or "best place to visit in San Francisco". تعرض واجهة برمجة التطبيقات المطابقات المرشحة استنادًا إلى هذه السلسلة وترتّب النتائج استنادًا إلى مدى صلتها بالموضوع.

  لضبط مَعلمة طلب البحث النصي، استخدِم طريقة 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.

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

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

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