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

پلاتفرم را انتخاب کنید: Android iOS JavaScript سرویس وب

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

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

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

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

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

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

// 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 در «جستجوی نوشتار» ازطریق روش getPagination() خود که یک شیء «صفحه‌بندی» را برمی‌گرداند، دسترسی به صفحه‌بندی نتایج جستجوی نوشتار را فراهم می‌کند.

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

وقتی hasNextPage() مقدار true را برمی‌گرداند، روش 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*
          * به‌جای Place.Field.NAME (منسوخ‌شده در نسخه ۴.۰) استفاده کنید.
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * حاوی نام منبع مکان به این شکل است: places/PLACE_ID.
           از DISPLAY_NAME برای دسترسی به نام نوشتاری مکان استفاده کنید.

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

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

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

      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() را فراخوانی کنید.

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

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

    برای تنظیم پارامتر حداقل رده‌بندی، هنگام ساختن شیء 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 یکسان هستند، با چند استثنای قابل‌توجه. برای مثال، ccTLD پادشاهی متحد «uk»‏ (co.uk.) است درحالی‌که کد ISO 3166-1 آن «gb» است (ازنظر فنی برای نهاد «پادشاهی متحد بریتانیای کبیر و ایرلند شمالی»). این پارامتر می‌تواند بر نتایج براساس قانون ذی‌ربط تأثیر بگذارد.

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

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

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

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