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

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

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

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

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

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

‫"10 High Street, UK" או "123 Main Street, US" יש כמה רחובות שנקראים High Street בבריטניה, וכמה רחובות שנקראים Main Street בארה"ב. השאילתה לא מחזירה תוצאות רצויות אלא אם מוגדרת הגבלת מיקום.
‫"ChainRestaurant New York" כמה מיקומים של 'מסעדה ברשת' בניו יורק; אין כתובת רחוב או אפילו שם רחוב.
‪"10 High Street, Escher UK" or "123 Main Street, Pleasanton US" יש רק רחוב אחד בשם High Street בעיר אֶשֶר בבריטניה, ורק רחוב אחד בשם Main Street בעיר פלזנטון בקליפורניה, ארה"ב.
‪"UniqueRestaurantName New York" יש רק מקום אחד בניו יורק עם השם הזה, ולא צריך לציין כתובת כדי להבדיל ביניהם.
‫"pizza restaurants in New York" (מסעדות פיצה בניו יורק) השאילתה הזו מכילה את הגבלת המיקום שלה, ו'פיצריות' הוא סוג מקום מוגדר היטב. היא מחזירה כמה תוצאות.
"+1 514-670-8700"

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

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

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

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

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

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

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