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

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

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

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

"הרצל 10, בריטניה" או "הרצל 12, ישראל"	מספר "רחובות ראשיים" בבריטניה, מספר "רחובות ראשיים" בארה"ב. השאילתה לא מחזירה תוצאות רצויות, אלא אם הוגדרה הגבלת מיקום.
"ChainRestaurant ניו יורק"	מספר סניפים של "ChainRestaurant" בניו יורק; אין שם רחוב או אפילו שם רחוב.
'הרצל 10, ישראל' או 'הרצל 111, ישראל"	רק "סטריט אחד" אחד בעיר אשר בבריטניה; רק "רחוב ראשי" אחד בעיר פלסנטון, קליפורניה.
"UniqueRestaurantName ניו יורק"	מוסד אחד בלבד עם השם הזה בניו יורק. אין צורך בכתובת פיזית כדי להבדיל בין השירותים.
"פיצה מסעדות בתל אביב"	השאילתה הזו מכילה את הגבלת המיקום שלה ו "פיצריות" הן סוג מוגדר היטב של מקום. התוצאה מחזירה מספר תוצאות.
"+1 514-670-8700"	השאילתה הזו מכילה מספר טלפון. היא מחזירה כמה תוצאות של מקומות שמשויכים למספר הטלפון הזה.

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

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

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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.NAME. כלומר, האובייקטים Place בתגובה שמייצגים כל מקום תואם מכילים רק את שני השדות האלה.

• משתמשים ב-SearchByTextRequest.Builder כדי ליצור אובייקט SearchByTextRequest שמגדיר את החיפוש.

  • מגדירים את מחרוזת הטקסט של שאילתת הטקסט ל-'Spicy צמחוני אוכל'.

  • עליך להגדיר את המספר המקסימלי של מקומות ל-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.NAME);

המשמעות של רשימת השדות הזו היא שכל אובייקט Place בתשובה מכיל רק את מזהה המקום והשם של כל מקום תואם. לאחר מכן אפשר להשתמש ב-methods Place.getId() ו-Place.getName() כדי לגשת לשדות האלה בכל אובייקט Place.

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

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

הפרמטרים הנדרשים ל-SearchByTextRequest הם:

• רשימת שדות

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

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

  צריך לציין אחד או יותר מהשדות הבאים:

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

    Place.Field.ID, Place.Field.NAME

  • השדות הבאים מפעילים את Text Search (Basic) SKU:

    Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

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

    Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, 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")

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

    צריך לאכלס גם את השדה 'נמוך' וגם את 'גבוה', והתיבה המיוצגת לא יכולה להיות ריקה. אזור תצוגה ריק יגרום לשגיאה.

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

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

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

• פתוח עכשיו

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

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

• רמות מחירים

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

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

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

• העדפת דירוג

  מציין איך התוצאות מדורגות בתשובה על סמך סוג השאילתה:

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

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

• קוד אזור

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

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

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

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

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

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

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