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

בחירת פלטפורמה: Android iOS JavaScript Web Service

מפתחים באזור הכלכלי האירופי (EEA)

התכונה "חיפוש טקסט (חדש)" מחזירה מידע על קבוצת מקומות על סמך מחרוזת (לדוגמה, "פיצה בניו יורק", "חנויות נעליים ליד אוטווה" או "רחוב הרצל 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.

חלוקה לדפים

הכיתה SearchByTextResponse של חיפוש טקסט מספקת גישה לחלוקה לדפים של תוצאות חיפוש באמצעות ה-method ‏getPagination(), שמחזירה אובייקט Pagination.

משתמשים ב-method ‏hasNextPage() של האובייקט Pagination כדי לקבוע אם יש דפי תוצאות נוספים. השיטה הזו מחזירה ערך בוליאני (true או false).

כל עוד hasNextPage() מחזיר את הערך true, צריך להפעיל את ה-method‏ 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();
        }
}

Java

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

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

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

    • השדות הבאים מפעילים את המק"ט "חיפוש טקסט בסיסי – מזהה בלבד":

      Place.Field.DISPLAY_NAME*
          * Use instead of Place.Field.NAME (deprecated in version 4.0).
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * מכיל את שם המשאב של המקום בפורמט: places/PLACE_ID.
           משתמשים ב-DISPLAY_NAME כדי לגשת לשם הטקסט של המקום.

      רשימה מלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

      רשימה מלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

      רשימה מלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

      רשימה מלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

  • שאילתת טקסט

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

    כדי להגדיר את פרמטר השאילתה של הטקסט, צריך להפעיל את ה-method‏ 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 מעלות ו-high.longitude = 180 מעלות, אזור התצוגה כולל את כל קווי האורך.
      • אם low.longitude = 180 מעלות ו-high.longitude = ‎-180 מעלות, טווח קווי האורך ריק.
      • אם low.latitude > high.latitude, טווח קווי הרוחב ריק.

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

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

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

  • הגבלת מיקום

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

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

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

  • מספר התוצאות המקסימלי

    מציין את המספר המקסימלי של תוצאות מקומות שיוחזרו. הערך חייב להיות בין 1 ל-20 (ברירת המחדל), כולל.

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

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

  • רמות מחירים

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

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

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