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

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

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

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

"10 High Street, UK" או "123Main Street, US" מספר "רחובות" בבריטניה; מספר "רחובות ראשיים" בארה"ב. השאילתה לא מחזירה תוצאות רצויות, אלא אם מוגדרת הגבלת מיקום.
"ChainRestaurant ניו יורק" מספר סניפים של "ChainRestaurant" בניו יורק, ללא רחוב או אפילו שם רחוב.
"10 High Street, Escher UK" או "123 הדרך הראשית, חיפה" רק "רחוב גבוה" אחד בעיר אשר בבריטניה; רק "רחוב ראשי" אחד בעיר פלסנטון בארה"ב.
"UniqueRestaurantName 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.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 שמגדיר את החיפוש.

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

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

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

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

הפרמטרים הנדרשים עבור SearchByTextRequest הם:

  • רשימת שדות

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

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

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

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

      Place.Field.ID, Place.Field.NAME

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

      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.

  • שאילתת טקסט

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

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

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

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

  • סוג כלול

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

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

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

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

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

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

  • הגבלת מיקום

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

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

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

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

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

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

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