חיפוש טקסט

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

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

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

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

  • רשימת שדות

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

  • שאילתת טקסט

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

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

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

  • סוג כלול

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

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

  • הטיית מיקום

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

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

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

    • מעגל מוגדר לפי נקודת מרכז ורדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50000.0, כולל. רדיוס ברירת המחדל הוא 0.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, טווח קווי הרוחב ריק.

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

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

  • הגבלת מיקום

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

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

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

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

  • דירוג מינימלי

    התוצאות יוגבלו רק למשתמשים שדירוג המשתמשים הממוצע שלהם גבוה מהמגבלה הזו או שווה לה. הערכים חייבים להיות בין 0.0 ל-5.0 (כולל) במרווחים של 0.5. לדוגמה: 0, 0.5, 1.0, ... , 5.0 כולל. הערכים יעוגלו כלפי מעלה ל-0.5 הקרוב ביותר. לדוגמה, הערך 0.6 מבטל את כל התוצאות שהדירוג שלהן נמוך מ-1.0.

  • פתוח עכשיו

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

  • רמות מחירים

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

    יש לציין רשימה של אחד או יותר מערכי המספרים השלמים הבאים:

    • 1 - PRICE_LEVEL_INEXPENSIVE
    • 2 - PRICE_LEVEL_MODERATE
    • 3 - PRICE_LEVEL_EXPENSIVE
    • 4 - PRICE_LEVEL_VERY_EXPENSIVE

  • העדפת דירוג

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

    הערכים כוללים:

    • SearchByTextRequest.RankPreference.DISTANCE: דירוג התוצאות לפי מרחק.
    • SearchByTextRequest.RankPreference.RELEVANCE: דירוג התוצאות לפי רלוונטיות.

  • קוד אזור

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

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

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

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

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