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

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

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

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

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

  • השדות הבאים מפעילים את 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 ל-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.

• הגבלת מיקום

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

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

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

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

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

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