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

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

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

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

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

"10 High Street, UK" یا "123 Main Street, US" چندین "های استریت" در بریتانیا؛ چندین "خیابان اصلی" در ایالات متحده پرس و جو نتایج مطلوبی را بر نمی گرداند مگر اینکه محدودیت مکانی تعیین شده باشد.
رستوران زنجیره ای نیویورک چندین مکان "ChainRestaurant" در نیویورک. بدون آدرس خیابان یا حتی نام خیابان.
"10 High Street, Escher UK" یا "123 Main Street, Pleasanton US" تنها یک «خیابان بالا» در شهر اسچر بریتانیا. تنها یک "خیابان اصلی" در شهر Pleasanton CA ایالات متحده.
"UniqueRestaurantName New York" تنها یک موسسه با این نام در نیویورک. هیچ آدرس خیابانی برای تفکیک لازم نیست.
"رستوران های پیتزا در نیویورک" این پرس و جو شامل محدودیت مکان آن است و "رستوران پیتزا" یک نوع مکان کاملاً تعریف شده است. چندین نتیجه را برمی گرداند.
"8700-670-514 1+"

این درخواست شامل یک شماره تلفن است. چندین نتیجه را برای مکان‌های مرتبط با آن شماره تلفن برمی‌گرداند.

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

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

// 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 ، فیلدهای داده شیء Access Place را ببینید

پارامترهای مورد نیاز

پارامترهای مورد نیاز SearchByTextRequest عبارتند از:

  • لیست زمینه

    مشخص کنید که فیلدهای داده کدام مکان برگردانده شوند. فهرستی از مقادیر Place.Field را ارسال کنید که فیلدهای داده را برای بازگشت مشخص می کند. هیچ لیست پیش فرضی از فیلدهای برگشتی در پاسخ وجود ندارد.

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

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

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

      Place.Field.DISPLAY_NAME
      Place.Field.ID
      Place.Field.RESOURCE_NAME

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

      Place.Field.ACCESSIBILITY_OPTIONS
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL
      Place.Field.LOCATION
      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

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

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_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.WEBSITE_URI

    • فیلدهای زیر Text Search Enterprise Plus SKU را فعال می کنند:

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

  • استعلام متنی

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

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

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

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

  • نوع شامل

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

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

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

  • تعصب مکان

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

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

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

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

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

      یک viewport یک منطقه بسته در نظر گرفته می شود، به این معنی که شامل مرز آن می شود. محدوده عرض جغرافیایی باید بین 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 ، محدوده عرض جغرافیایی خالی است.

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

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

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

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

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

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

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

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

    حداکثر تعداد نتایج مکان برای بازگشت را مشخص می کند. باید بین 1 تا 20 (پیش‌فرض) باشد.

    برای تنظیم حداکثر پارامتر تعداد نتیجه، هنگام ساخت شی 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 - Place خدمات ارزان قیمت ارائه می دهد.
    • 2 - Place خدمات با قیمت متوسط ​​ارائه می دهد.
    • 3 - Place خدمات گران قیمتی ارائه می دهد.
    • 4 - Place خدمات بسیار گرانی ارائه می دهد.

    برای تنظیم پارامتر سطوح قیمت، هنگام ساخت شی 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 type استفاده می شود. هنگامی که روی true تنظیم شود، تنها مکان هایی که با انواع مشخص شده با نوع include مطابقت دارند برگردانده می شوند. هنگامی که false ، پیش‌فرض است، پاسخ می‌تواند حاوی مکان‌هایی باشد که با انواع مشخص‌شده مطابقت ندارند.

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