חיפוש טקסט (חדש)

החיפוש באמצעות טקסט (חדש) מחזיר מידע על קבוצת מקומות על סמך מחרוזת (לדוגמה, 'פיצה בניו יורק', 'חנויות נעליים ליד אוטווה' או 'רחוב הראשי 123'). השירות מגיב עם רשימת מקומות שתואמים למחרוזת הטקסט ולכל הטיה של מיקום שהוגדרה.

בנוסף לפרמטרים הנדרשים, בחיפוש טקסט (חדש) אפשר לשפר את התוצאות באמצעות פרמטרים אופציונליים.

חיפוש טקסט (חדש) דומה לחיפוש בסביבה (חדש). ההבדל העיקרי בין שני השירותים הוא שבחיפוש טקסט (חדש) אפשר לציין מחרוזת חיפוש שרירותית, בעוד שבחיפוש בסביבה (חדש) צריך לציין אזור מסוים לחיפוש.

בקשות לחיפוש טקסט

בקשה לחיפוש טקסט היא מהצורה:

// 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" (אוכל צמחוני חריף).

  • מגדירים את המספר המקסימלי של מקומות בתוצאות ל-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 בתשובה מכיל רק את מזהה המקום ואת השם של כל מקום שתואם לחיפוש. לאחר מכן תוכלו להשתמש ב-methods‏ Place.getId() ו-Place.getName() כדי לגשת לשדות האלה בכל אובייקט Place.

דוגמאות נוספות לגישה לנתונים באובייקט Place זמינות במאמר גישה לשדות נתונים של אובייקט Place.

פרמטרים נדרשים

הפרמטרים הנדרשים עבור SearchByTextRequest הם:

• רשימת השדות

  מציינים אילו שדות של נתוני מקומות רוצים להחזיר. מעבירים רשימה של ערכים Place.Field שמציינים את שדות הנתונים שרוצים להחזיר. אין רשימת ברירת מחדל של שדות שמוחזרים בתגובה.

  שימוש ברשימות שדות הוא שיטה מומלצת לעיצוב, כדי לוודא שלא מתבצעת בקשה לנתונים מיותרים. כך אפשר להימנע מזמן עיבוד מיותר ומחיובים מיותרים.

  מציינים אחד או יותר מהשדות הבאים:

  • השדות הבאים מפעילים את Text Search Essentials ID Only SKU:

    Place.Field.DISPLAY_NAME*
        * שימוש במקום Place.Field.NAME (הוצא משימוש בגרסה 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

  • השדות הבאים מפעילים את מק"ט Text Search 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

  • השדות הבאים מפעילים את מק"ט 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

  כדי להגדיר את הפרמטר של רשימת השדות, קוראים לשיטה setPlaceFields() כשיוצרים את האובייקט SearchByTextRequest.

• שאילתת טקסט

  מחרוזת הטקסט שרוצים לחפש, לדוגמה: 'מסעדה', 'רחוב ראשי 123' או 'המקום הכי טוב לבקר בו בתל אביב'. ה-API מחזיר התאמות למועמדים על סמך המחרוזת הזו ומסדר את התוצאות על סמך מידת הרלוונטיות שלהן.

  כדי להגדיר את פרמטר השאילתה של הטקסט, קוראים למתודה setTextQuery() כשיוצרים את האובייקט SearchByTextRequest.

פרמטרים אופציונליים

משתמשים באובייקט SearchByTextRequest כדי לציין את הפרמטרים האופציונליים של הבקשה.

• סוג ההכללה

  הגבלת התוצאות למקומות שתואמים לסוג שצוין ומוגדר בטבלה א'. אפשר לציין רק סוג אחד. לדוגמה:

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

  כדי להגדיר את פרמטר הסוג הכלול, צריך לבצע קריאה ל-method‏ 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, טווח קווי הרוחב ריק.

    צריך להזין ערך נמוך וערך גבוה, והתיבה שמייצגים לא יכולה להיות ריקה. אם אזור התצוגה ריק, תופיע שגיאה.

    לדוגמה, בקשות לחיפוש טקסט בתיבת תצוגה מלבנית מפורטות במאמר בנושא בקשות לחיפוש טקסט.

    כדי להגדיר את פרמטר הטיית המיקום, צריך לבצע קריאה ל-method‏ setLocationBias() כשיוצרים את האובייקט SearchByTextRequest.

• הגבלת מיקום

  מציין אזור לחיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין. מגדירים את האזור כאזור תצוגה מלבני. למידע על הגדרת אזור התצוגה, אפשר לעיין בתיאור של הטיה לפי מיקום.

  אפשר לציין הגבלת מיקום או הטיה למיקום, אבל לא את שניהם. הגבלת מיקום היא הגדרת האזור שבו התוצאות צריכות להיות, והטיה לפי מיקום היא הגדרת האזור שבו התוצאות צריכות להיות קרובות, אבל הן יכולות להיות גם מחוץ לאזור.

  כדי להגדיר את פרמטר הגבלת המיקום, צריך לבצע קריאה ל-method‏ 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.

  כדי להגדיר את פרמטר הדירוג המינימלי, צריך להפעיל את method‏ setMinRating() כשיוצרים את האובייקט SearchByTextRequest.

• פתוח עכשיו

  אם true, מחזיר רק את המקומות שפתוחים לעסקים בזמן שליחת השאילתה. אם false, יוחזרו כל העסקים ללא קשר לסטטוס הפתיחה. אם לא מצוינים שעות פתיחה במאגר הנתונים של Google Places, המקומות האלה יוחזרו אם תגדירו את הפרמטר הזה לערך false.

  כדי להגדיר את הפרמטר open now, צריך לבצע קריאה ל-method‏ setOpenNow() כשיוצרים את האובייקט SearchByTextRequest.

• רמות מחירים

  כברירת מחדל, התוצאות כוללות מקומות שמספקים שירותים בכל רמות המחירים. כדי להגביל את התוצאות כך שיכללו רק מקומות ברמות מחיר מסוימות, אפשר להעביר רשימה של ערכים מספריים שמתאימים לרמות המחיר של המקומות שרוצים להחזיר:

  • 1 – המקום מספק שירותים זולים.
  • ‫2 – המקום מספק שירותים במחירים בינוניים.
  • ‫3 – המקום מספק שירותים יקרים.
  • ‫4 – המקום מספק שירותים יקרים מאוד.

  כדי להגדיר את הפרמטר price levels, קוראים לשיטה setPriceLevels() כשיוצרים את האובייקט SearchByTextRequest.

• העדפת דירוג

  מציינים איך התוצאות מדורגות בתגובה לפי סוג השאילתה:

  • עבור שאילתה קטגורית כמו 'מסעדות בניו יורק', ‫SearchByTextRequest.RankPreference.RELEVANCE (דירוג התוצאות לפי הרלוונטיות לחיפוש) היא ברירת המחדל. אפשר להגדיר את העדפת הדירוג ל-SearchByTextRequest.RankPreference.RELEVANCE או ל-SearchByTextRequest.RankPreference.DISTANCE (דירוג התוצאות לפי מרחק).
  • לשאילתה לא קטגורית כמו 'Mountain View, CA', מומלץ לא להגדיר את פרמטר העדפת הדירוג.

  כדי להגדיר את פרמטר העדפת הדירוג, צריך לבצע קריאה ל-method‏ setRankPreference() כשיוצרים את האובייקט SearchByTextRequest.

• קוד אזור

  קוד האזור שמשמש לעיצוב התשובה, שמוגדר כערך קוד CLDR באורך שני תווים. הפרמטר הזה יכול גם להטות את תוצאות החיפוש. אין ערך ברירת מחדל.

  אם שם המדינה בשדה הכתובת בתגובה זהה לקוד האזור, קוד המדינה מושמט מהכתובת.

  רוב הקודים של CLDR זהים לקודי ISO 3166-1, אבל יש כמה יוצאים מן הכלל. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'ממלכת בריטניה הגדולה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

  כדי להגדיר את פרמטר קוד האזור, צריך לבצע קריאה ל-method‏ setRegionCode() כשיוצרים את האובייקט SearchByTextRequest.

• סינון קפדני לפי סוג

  משמש עם הפרמטר include type. אם המאפיין מוגדר לערך true, מוחזרים רק מקומות שתואמים לסוגים שצוינו במאפיין include type. כשהערך הוא false (ברירת המחדל), התגובה יכולה להכיל מקומות שלא תואמים לסוגים שצוינו.

  כדי להגדיר את הפרמטר לסינון קפדני של סוגים, צריך לבצע קריאה ל-method‏ setStrictTypeFiltering() כשיוצרים את האובייקט SearchByTextRequest.