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