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

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

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

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

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

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

// 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.

חלוקה לדפים

הגישה לתוצאות החיפוש של Text Search מחולקת לדפים באמצעות המחלקה 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 שמציינים את שדות הנתונים שיוחזרו. אין רשימת ברירת מחדל של שדות שמוחזרים בתשובה.

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

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

  • השדות הבאים מפעילים את 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 מחזיר התאמות למועמדים על סמך המחרוזת הזו ומסדר את התוצאות על סמך מידת הרלוונטיות שלהן.

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

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

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

• סוג ההכללה

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

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

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

• הטיה לפי מיקום

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

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

  מגדירים את האזור כתיבת תצוגה מלבנית או כמעגל.

  • מעגל מוגדר על ידי נקודת מרכז ורדיוס במטרים. הערך של רדיוס חייב להיות בין 0.0 ל-50,000.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 degrees ו-high.longitude = ‎180 degrees, אז אזור התצוגה כולל את כל קווי האורך.
    • אם 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 – המקום מספק שירותים יקרים מאוד.

  כדי להגדיר את הפרמטר של רמות המחירים, קוראים למתודה 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.