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

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

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

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

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

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

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

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

  • רשימת שדות

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

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

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

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

      Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME

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

      Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, 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

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

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_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.WEBSITE_URI

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

      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

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

  • שאילתה בטקסט

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

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

      צריך לאכלס את הערכים של low ו-high, והתיבה המיוצגת לא יכולה להיות ריקה. תצוגת חלון ריקה גורמת לשגיאה.

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

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

  • הגבלת מיקום

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

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

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

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

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

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

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

  • רמות מחירים

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

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

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

  • העדפת דירוג

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

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

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

  • קוד אזור

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

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

    רוב קודי CLDR זהים לקודי ISO 3166-1, מלבד כמה חריגים בולטים. לדוגמה, הדומיין ברמה העליונה של בריטניה הוא ‎"uk" (‎.co.uk), והקוד שלו לפי תקן ISO 3166-1 הוא ‎"gb" (טכנית, הישות היא ‎"The United Kingdom of Great Britain and Northern Ireland"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

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

  • סינון נוקשה של סוגי פריטים

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

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