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

اختيار النظام الأساسي: Android iOS JavaScript خدمة ويب

المطوّرون في المنطقة الاقتصادية الأوروبية

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

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

تتشابه خدمة Text Search (New) مع خدمة Nearby Search (New). يتمثّل الفرق الرئيسي بينهما في أنّ البحث النصي (New) تتيح لك تحديد سلسلة بحث عشوائية، بينما تتطلّب بحث في الجوار (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 يحدّد عملية البحث.

    • اضبط سلسلة طلب البحث النصي على "طعام نباتي حار".

    • اضبط الحد الأقصى لعدد الأماكن في النتائج على 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() التي تعرض كائن تقسيم الصفحات.

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

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

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

Kotlin

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 تحدّد حقول البيانات المطلوب عرضها. لا تتوفّر قائمة تلقائية بالحقول التي يتم عرضها في الاستجابة.

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

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

    • تؤدي الحقول التالية إلى تفعيل رمز التخزين التعريفي (SKU) لخدمة Text Search Essentials (المعرّف فقط):

      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.

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