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

בחירת פלטפורמה: 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 בתשובה מכיל רק את מזהה המקום ואת השם של כל מקום שתואם לחיפוש. אחר כך אפשר להשתמש ב-method‏ Place.getId() וב-method‏ 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 שמציינים את שדות הנתונים שיוחזרו. אין רשימת ברירת מחדל של שדות שמוחזרים בתשובה.

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

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

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

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

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

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

  • שאילתת טקסט

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

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

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

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

  • סינון סוגים מחמיר

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

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