جستجوی متن (جدید)

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

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

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

درخواست‌های جستجوی متن

درخواست جستجوی متن به شکل زیر است:

// 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 که جستجو را تعریف می‌کند، استفاده کنید.

  • رشته پرس و جوی متن را روی "غذاهای تند گیاهی" تنظیم کنید.

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

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

• یک 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 مراجعه کنید.

صفحه بندی

کلاس SearchByTextResponse در جستجوی متن، از طریق متد getPagination() خود که یک شیء Pagination برمی‌گرداند، امکان دسترسی به صفحه‌بندی نتایج جستجوی متن را فراهم می‌کند.

از متد hasNextPage() شیء Pagination برای تعیین اینکه آیا صفحات اضافی نتایج در دسترس هستند یا خیر، استفاده کنید. این متد یک مقدار بولی (true یا false) برمی‌گرداند.

در حالی که hasNextPage() مقدار true را برمی‌گرداند، متد 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 مربوط به جستجوی متنی ملزومات با شناسه‌ی فقط (Text Search Essentials ID Only SKU) را فعال می‌کنند:

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

  • فیلدهای زیر SKU مربوط به 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

  • فیلدهای زیر SKU مربوط به جستجوی متنی Enterprise را فعال می‌کنند:

    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

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

• پرس و جوی متنی

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

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

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

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

• نوع شامل

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

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

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

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

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

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

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

  • یک دایره با نقطه مرکز و شعاع بر حسب متر تعریف می‌شود. شعاع باید بین 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();

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

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

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

    هر دو پارامتر low و high باید پر شوند و کادر نمایش داده شده نمی‌تواند خالی باشد. یک viewport خالی منجر به خطا می‌شود.

    برای مثال، برای یک نمای مستطیلی، به درخواست‌های جستجوی متن مراجعه کنید.

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

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

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

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

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

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

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

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

• حداقل امتیاز

  نتایج را فقط به مواردی محدود می‌کند که میانگین امتیاز کاربران آنها بزرگتر یا مساوی این حد باشد. مقادیر باید بین 0.0 تا 5.0 (شامل) با گام‌های 0.5 باشند. برای مثال: 0، 0.5، 1.0، ...، 5.0 (شامل). مقادیر به نزدیکترین عدد 0.5 به بالا گرد می‌شوند. برای مثال، مقدار 0.6 تمام نتایج با امتیاز کمتر از 1.0 را حذف می‌کند.

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

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

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

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

• سطوح قیمت

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

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

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

• ترجیح رتبه

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

  • برای یک عبارت جستجوی دسته‌بندی‌شده مانند «رستوران‌ها در شهر نیویورک»، SearchByTextRequest.RankPreference.RELEVANCE (رتبه‌بندی نتایج بر اساس ارتباط جستجو) پیش‌فرض است. می‌توانید اولویت رتبه‌بندی را روی SearchByTextRequest.RankPreference.RELEVANCE یا SearchByTextRequest.RankPreference.DISTANCE (رتبه‌بندی نتایج بر اساس فاصله) تنظیم کنید.
  • برای یک پرس‌وجوی غیرطبقه‌ای مانند «مانتین ویو، کالیفرنیا»، توصیه می‌کنیم پارامتر ترجیح رتبه را بدون تنظیم رها کنید.

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

• کد منطقه

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

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

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

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

• فیلترینگ دقیق نوع

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

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