جستجوی نوشتار (جدید)

«جستجوی نوشتاری» (جدید) اطلاعات مربوط به مجموعه‌ای از مکان‌ها را براساس رشته‌ای (برای مثال، «پیتزا در تهران» یا «کفش‌فروشی‌های اطراف اصفهان» یا «خیابان اصلی ۱۲۳») برمی‌گرداند. سرویس با فهرستی از مکان‌های منطبق با رشته نوشتاری و هرگونه سوگیری مکانی که تنظیم شده است پاسخ می‌دهد.

علاوه‌بر پارامترهای الزامی، «جستجوی نوشتاری» (جدید) از پالایش پُرسمان‌ها بااستفاده از پارامترهای اختیاری برای نتایج بهتر پشتیبانی می‌کند.

«جستجوی نوشتاری» (جدید) شبیه جستجوی اطراف (جدید) است. تفاوت اصلی بین این دو این است که «جستجوی نوشتاری (جدید)» به شما امکان می‌دهد رشته جستجوی دلخواهی را مشخص کنید، درحالی‌که «جستجوی اطراف (جدید)» به منطقه مشخصی برای جستجو نیاز دارد.

درخواست‌های «جستجوی نوشتار»

درخواست «جستجوی نوشتاری» به‌صورت زیر است:

// 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» (غذای گیاهی تند) تنظیم کنید.

  • حداکثر تعداد مکان‌های نتیجه را روی ۱۰ تنظیم کنید. پیش‌فرض و حداکثر ۲۰ است.

  • محدوده جستجو را به مستطیل تعریف‌شده با مختصات طول و عرض جغرافیایی محدود کنید. هیچ موردی خارج از این منطقه برگردانده نمی‌شود.

• 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() شیء Pagination استفاده کنید تا مشخص شود آیا صفحه‌های بیشتری از نتایج دردسترس است یا نه. این روش مقدار بولی (درست یا نادرست) برمی‌گرداند.

تا زمانی که 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 مقادیر را ارسال کنید که فیلدهای داده را برای برگرداندن مشخص می‌کند. هیچ فهرست پیش‌فرضی از فیلدهای برگردانده‌شده در پاسخ وجود ندارد.

  فهرست‌های فیلد روش طراحی خوبی برای اطمینان از این است که داده‌های غیرضروری درخواست نمی‌کنید، که به جلوگیری از زمان پردازش غیرضروری و هزینه‌های صورت‌حساب کمک می‌کند.

  یک یا چند فیلد زیر را مشخص کنید:

  • فیلدهای زیر شناسه SKU فقط ضروریات جستجوی نوشتاری را راه‌اندازی می‌کنند:

    Place.Field.DISPLAY_NAME*
        * به‌جای Place.Field.NAME (منسوخ‌شده در نسخه ۴.۰) استفاده کنید.
    Place.Field.ID
Place.Field.RESOURCE_NAME*
        * حاوی نام منبع مکان به این شکل است: places/PLACE_ID.
         برای دسترسی به نام نوشتاری مکان، از DISPLAY_NAME استفاده کنید.

    برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.

  • فیلدهای زیر Text Search Pro SKU را راه‌اندازی می‌کنند:

    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

    برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.

  • فیلدهای زیر واحد نگهداری موجودی سازمانی جستجوی نوشتاری را راه‌اندازی می‌کنند:

    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

    برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.

  • فیلدهای زیر شناسه محصول Text Search 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

    برای مشاهده فهرست کامل فیلدها و SKUهای مرتبط با آن‌ها، به فیلدهای داده مکان (جدید) مراجعه کنید.

  برای تنظیم پارامتر فهرست فیلد، هنگام ساختن شیء SearchByTextRequest، روش setPlaceFields() را فراخوانی کنید.

• پُرسمان نوشتاری

  رشته نوشتاری که باید جستجو شود، برای مثال: «رستوران»، «خیابان اصلی ۱۲۳»، یا «بهترین مکان برای بازدید در سان‌فرانسیسکو». ‫API مطابقت‌های نامزد را براساس این رشته برمی‌گرداند و نتایج را براساس ارتباط درک‌شده آن‌ها مرتب می‌کند.

  برای تنظیم پارامتر پُرسمان نوشتاری، هنگام ساختن شیء SearchByTextRequest، روش setTextQuery() را فراخوانی کنید.

پارامترهای اختیاری

از شیء SearchByTextRequest برای مشخص کردن پارامترهای اختیاری درخواستتان استفاده کنید.

• نوع گنجانده‌شده

  نتایج را به مکان‌هایی محدود می‌کند که با نوع مشخص‌شده تعریف‌شده توسط جدول الف مطابقت دارند. فقط یک نوع را می‌توان مشخص کرد. برای مثال:

  • setIncludedType("bar")
  • setIncludedType("pharmacy")

  برای تنظیم پارامتر نوع گنجانده‌شده، هنگام ساختن شیء SearchByTextRequest، روش setIncludedType() را فراخوانی کنید.

• سوگیری مکانی

  منطقه‌ای را برای جستجو مشخص می‌کند. این مکان به‌عنوان گرایش عمل می‌کند، یعنی نتایج اطراف مکان مشخص‌شده می‌تواند برگردانده شود، ازجمله نتایج خارج از منطقه مشخص‌شده.

  می‌توانید محدودیت مکان یا سوگیری مکان را مشخص کنید، اما نه هر دو را. محدودیت مکان را به‌عنوان مشخص کردن منطقه‌ای درنظر بگیرید که نتایج باید در آن باشد، و گرایش مکان را به‌عنوان مشخص کردن منطقه‌ای درنظر بگیرید که نتایج احتمالاً در آن یا نزدیک آن خواهد بود — به‌خاطر داشته باشید که هنگام استفاده از گرایش مکان، نتایج همچنان می‌تواند خارج از منطقه مشخص‌شده باشد.

  منطقه را به‌عنوان «درگاه نمایش مستطیلی» یا دایره مشخص کنید.

  • دایره با نقطه مرکزی و شعاع برحسب متر تعریف می‌شود. شعاع باید بین ۰٫۰ و ۵۰۰۰۰٫۰ باشد و می‌تواند این دو عدد را نیز دربر بگیرد. برای مثال:

    // 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();

  • مستطیل نمای دید طول و عرض جغرافیایی است که به‌صورت دو نقطه پایین و بالای مورب مخالف نشان داده می‌شود. نقطه پایین نشان‌دهنده گوشه جنوب غربی مستطیل است و نقطه بالا نشان‌دهنده گوشه شمال شرقی مستطیل است.

    ناحیه نمایش به‌عنوان یک منطقه بسته درنظر گرفته می‌شود، یعنی مرزهای آن را دربرمی‌گیرد. محدوده عرض جغرافیایی باید بین ۹۰- تا ۹۰ درجه باشد، و محدوده طول جغرافیایی باید بین ۱۸۰- تا ۱۸۰ درجه باشد:

    • اگر low = high، ناحیه نمایش از آن نقطه واحد تشکیل می‌شود.
    • اگر low.longitude > high.longitude، محدوده طول جغرافیایی معکوس می‌شود (ناحیه نمایش از خط طول جغرافیایی ۱۸۰ درجه عبور می‌کند).
    • اگر low.longitude = -۱۸۰ درجه و high.longitude = ۱۸۰ درجه باشد، درگاه دید همه طول‌های جغرافیایی را دربرمی‌گیرد.
    • اگر low.longitude = ۱۸۰ درجه و high.longitude = ۱۸۰- درجه باشد، محدوده طول جغرافیایی خالی است.
    • اگر low.latitude > high.latitude، محدوده عرض جغرافیایی خالی است.

    هر دو مقدار کم و زیاد باید پر شوند و کادر نمایش‌داده‌شده نمی‌تواند خالی باشد. درگاه دید خالی منجر به خطا می‌شود.

    برای مثال، از درگاه دید مستطیلی، درخواست‌های «جستجوی نوشتاری» را ببینید.

    برای تنظیم پارامتر گرایش مکان، هنگام ساختن شیء SearchByTextRequest، روش setLocationBias() را فراخوانی کنید.

• محدودیت مکان

  منطقه‌ای را برای جستجو مشخص می‌کند. نتایج خارج از منطقه مشخص‌شده برگردانده نمی‌شود. منطقه را به‌عنوان «نمای مستطیلی» مشخص کنید. برای اطلاعات درباره تعریف «نمای هدف»، شرح سوگیری مکان را ببینید.

  می‌توانید محدودیت مکان یا گرایش مکان را مشخص کنید، اما نمی‌توانید هر دو را مشخص کنید. محدودیت مکان را به‌عنوان مشخص کردن منطقه‌ای درنظر بگیرید که نتایج باید در آن باشد، و گرایش مکان را به‌عنوان مشخص کردن منطقه‌ای درنظر بگیرید که نتایج باید نزدیک آن باشد اما می‌تواند خارج از آن منطقه باشد.

  برای تنظیم پارامتر محدودیت مکان، هنگام ساختن شیء SearchByTextRequest، روش setLocationRestriction() را فراخوانی کنید.

• حداکثر تعداد نتایج

  حداکثر تعداد نتایج مکان را برای برگرداندن مشخص می‌کند. باید بین ۱ و ۲۰ (پیش‌فرض) باشد.

  برای تنظیم پارامتر حداکثر تعداد نتایج، هنگام ساختن شیء SearchByTextRequest، روش setMaxResultCount() را فراخوانی کنید.

• حداقل رده‌بندی

  نتایج را فقط به مواردی محدود می‌کند که میانگین رده‌بندی کاربر آن‌ها بیشتر از یا برابر با این حد باشد. مقادیر باید بین ۰٫۰ و ۵٫۰ (شامل این دو عدد) با افزایش ۰٫۵ باشد. برای مثال: ۰، ۰٫۵، ۱٫۰، …، ۵٫۰ شامل این دو عدد. مقادیر به نزدیک‌ترین ۰٫۵ گرد می‌شوند. برای مثال، مقدار ۰٫۶ همه نتایج با رده‌بندی کمتر از ۱٫۰ را حذف می‌کند.

  برای تنظیم پارامتر حداقل رده‌بندی، هنگام ساختن شیء SearchByTextRequest، روش setMinRating() را فراخوانی کنید.

• اکنون باز است

  اگر true، فقط مکان‌هایی را برگردانید که در زمان ارسال پُرسمان برای کسب‌وکار باز هستند. اگر false، همه کسب‌وکارها را صرف‌نظر از وضعیت باز بودن برگردانید. اگر این پارامتر را روی false تنظیم کنید، مکان‌هایی که ساعات کاری را در پایگاه داده Google Places مشخص نکرده‌اند برگردانده می‌شوند.

  برای تنظیم پارامتر «اکنون باز است»، هنگام ساختن شیء SearchByTextRequest، روش setOpenNow() را فراخوانی کنید.

• سطوح قیمت

  به‌طور پیش‌فرض، نتایج شامل مکان‌هایی است که خدمات را در همه سطوح قیمت ارائه می‌دهند. برای محدود کردن نتایج به‌گونه‌ای که فقط شامل مکان‌هایی با سطوح قیمت خاص باشد، می‌توانید فهرستی از مقادیر عدد صحیح را که با سطوح قیمت مکان‌هایی که می‌خواهید برگردانده شوند مطابقت دارد ارسال کنید:

  • 1 - این مکان خدمات ارزان ارائه می‌دهد.
  • 2 - مکان خدمات با قیمت متوسط ارائه می‌دهد.
  • ‫3 - مکان خدمات گران ارائه می‌دهد.
  • 4 - این مکان خدمات بسیار گرانی ارائه می‌دهد.

  برای تنظیم پارامتر سطوح قیمت، هنگام ساختن شیء SearchByTextRequest، روش setPriceLevels() را فراخوانی کنید.

• اولویت رتبه

  مشخص می‌کند که نتایج در پاسخ براساس نوع پرسمان چگونه رتبه‌بندی شوند:

  • برای پُرسمان دسته‌ای مثل «رستوران‌های تهران»، SearchByTextRequest.RankPreference.RELEVANCE (رتبه‌بندی نتایج براساس ارتباط جستجو) پیش‌فرض است. می‌توانید اولویت رتبه‌بندی را روی SearchByTextRequest.RankPreference.RELEVANCE یا SearchByTextRequest.RankPreference.DISTANCE (رتبه‌بندی نتایج براساس فاصله) تنظیم کنید.
  • برای پُرسمان غیردسته‌بندی‌شده‌ای مثل «Mountain View, CA»، توصیه می‌کنیم پارامتر اولویت رتبه را تنظیم‌نشده رها کنید.

  برای تنظیم پارامتر اولویت رتبه، هنگام ساختن شیء SearchByTextRequest، روش setRankPreference() را فراخوانی کنید.

• کد منطقه

  کد منطقه‌ای که برای قالب‌بندی پاسخ استفاده می‌شود، به‌عنوان مقدار کد CLDR دو نویسه‌ای مشخص شده است. این پارامتر همچنین می‌تواند تأثیر سوگیرانه‌ای بر نتایج جستجو داشته باشد. مقدار پیش‌فرضی وجود ندارد.

  اگر نام کشور فیلد نشانی در پاسخ با کد منطقه مطابقت داشته باشد، کد کشور از نشانی حذف می‌شود.

  اکثر کدهای CLDR با کدهای ISO 3166-1 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، دامنه سطح بالای کد کشور پادشاهی متحد «uk»‏ (co.uk.) است، درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»). این پارامتر می‌تواند بر نتایج براساس قانون ذی‌ربط تأثیر بگذارد.

  برای تنظیم پارامتر کد منطقه، هنگام ساختن شیء SearchByTextRequest، روش setRegionCode() را فراخوانی کنید.

• فیلتر کردن نوع سخت‌گیرانه

  با پارامتر نوع گنجاندن استفاده می‌شود. وقتی روی true تنظیم شود، فقط مکان‌هایی که با انواع مشخص‌شده توسط include type مطابقت داشته باشند برگردانده می‌شوند. وقتی false، پیش‌فرض، پاسخ می‌تواند حاوی مکان‌هایی باشد که با انواع مشخص‌شده مطابقت ندارند.

  برای تنظیم پارامتر فیلتر کردن نوع سخت‌گیرانه، هنگام ساختن شیء SearchByTextRequest، روش setStrictTypeFiltering() را فراخوانی کنید.