חיפוש טקסט מחזיר מידע על קבוצה של מקומות לפי מחרוזת. לדוגמה, "פיצה בתל אביב", "חנויות נעליים ליד רוטשילד" או "הרצל 12". בתגובה השירות מוצגת רשימת מקומות שתואמים למחרוזת הטקסט ולכל הטיית מיקום מוגדרת.
השירות הזה שימושי במיוחד לביצוע שאילתות לא חד-משמעיות לגבי כתובות במערכת אוטומטית, ורכיבים שאינם כתובות במחרוזת עשויים להתאים לעסקים וגם לכתובות. דוגמאות לשאילתות לא חד-משמעיות של כתובת הן כתובות בפורמט לא תקין או בקשות שכוללות רכיבים שהם לא כתובות, כמו שמות עסקים. בקשות כמו שתי הדוגמאות הראשונות עשויות להחזיר אפס תוצאות, אלא אם מוגדר מיקום (למשל אזור, הגבלת מיקום או הטיית מיקום).
"הרצל 10, בריטניה" או "הרצל 12, ישראל" | מספר "רחובות ראשיים" בבריטניה, מספר "רחובות ראשיים" בארה"ב. השאילתה לא מחזירה תוצאות רצויות, אלא אם הוגדרה הגבלת מיקום. |
"Chain restaurant New York" | מספר מיקומים של "מסעדת רשת" בניו יורק; אין כתובת פיזית או אפילו שם רחוב. |
'הרצל 10, ישראל' או 'הרצל 111, ישראל" | רק "סטריט אחד" אחד בעיר אשר בבריטניה; רק "רחוב ראשי" אחד בעיר פלסנטון, קליפורניה. |
"UniqueRestaurantName ניו יורק" | מוסד אחד בלבד עם השם הזה בניו יורק. אין צורך בכתובת פיזית כדי להבדיל בין השירותים. |
"פיצה מסעדות בתל אביב" | השאילתה הזו מכילה את הגבלת המיקום שלה ו "פיצריות" הן סוג מוגדר היטב של מקום. התוצאה מחזירה מספר תוצאות. |
"+1 514-670-8700" | השאילתה הזו מכילה מספר טלפון. היא מחזירה כמה תוצאות של מקומות שמשויכים למספר הטלפון הזה. |
קבלת רשימה של מקומות באמצעות חיפוש טקסט
כדי לשלוח בקשת חיפוש טקסט, שולחים קריאה ל-GMSPlacesClient
searchByTextWithRequest:
ומעבירים אובייקט GMSPlaceSearchByTextRequest
שמגדיר את הפרמטרים של הבקשה ושיטת קריאה חוזרת (callback) מסוג GMSPlaceSearchByTextResultCallback
.
האובייקט GMSPlaceSearchByTextRequest
מציין את כל הפרמטרים החובה והאופציונליים לבקשה. הפרמטרים הנדרשים הם:
- רשימת השדות שצריך להחזיר באובייקט
GMSPlace
, שנקראת גם field mask, שמוגדר על ידיGMSPlaceProperty
. אם לא תציינו לפחות שדה אחד ברשימת השדות, או אם משמיטים את רשימת השדות, הקריאה תחזיר שגיאה. - שאילתת הטקסט.
הדוגמה הזו לחיפוש טקסט מציינת שהאובייקטים של התגובה GMSPlace
מכילים את שם המקום ומזהה המקום של כל אובייקט GMSPlace
בתוצאות החיפוש. הוא גם מסנן את התשובה כדי להציג רק מקומות מסוג 'מסעדה'.
Swift
// Create the GMSPlaceSearchByTextRequest object. let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID]; let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue] request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2D(latitude: 20, longitude: 30), CLLocationCoordinate2D(latitude: 40, longitude: 50) ) // Array to hold the places in the response placeResults = []; let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } self.placeResults = results } GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)
Objective-C
// Create the GMSPlaceSearchByTextRequest object. GMSPlaceSearchByTextRequest *request = [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]]; request.isOpenNow = YES; request.includedType = @"restaurant"; request.maxResultCount = 5; request.minRating = 3.5; request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance; request.isStrictTypeFiltering = YES; request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ]; request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50)); request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } }];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
תשובות לחיפוש טקסט
ה-Text Search API מחזיר מערך של התאמות בצורת אובייקטים GMSPlace
, עם אובייקט GMSPlace
אחד לכל מקום תואם.
יחד עם שדות הנתונים, האובייקט GMSPlace
בתשובה מכיל את פונקציות החברות הבאות:
-
isOpen
מחשב אם המקום פתוח בזמן נתון. - הפונקציה
isOpenAtDate
מחשבת אם המקום פתוח בתאריך נתון.
פרמטרים נדרשים
משתמשים באובייקט GMSPlaceSearchByTextRequest
כדי לציין את הפרמטרים הנדרשים לחיפוש.
-
רשימת שדות
יש לציין אילו מאפיינים של נתוני מקום להחזיר. מעבירים רשימה של המאפיינים ב-
GMSPlace
שמציינים את שדות הנתונים שיוחזרו. אם משמיטים את מסיכת השדה, הבקשה תחזיר שגיאה.מומלץ ליצור רשימות של שדות כדי לא לבקש נתונים מיותרים, וכך לחסוך זמן עיבוד וחיובים מיותרים.
צריך לציין אחד או יותר מהשדות הבאים:
השדות הבאים מפעילים את המק"ט של חיפוש טקסט (מזהה בלבד):
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
השדות הבאים מפעילים את Text Search (Basic) SKU:
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
,GMSPlacePropertyWheelchairAccessibleEntrance
השדות הבאים מפעילים את מק"ט של חיפוש טקסט (מתקדם):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
השדות הבאים מפעילים את מק"ט של חיפוש טקסט (מועדף):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
,GMSPlacePropertyTakeout
-
textQuery
מחרוזת הטקסט שיש לחפש לפיה, לדוגמה: "מסעדה", "רחוב ראשי 12" או "המקום הטוב ביותר לביקור בתל אביב".
פרמטרים אופציונליים
משתמשים באובייקט GMSPlaceSearchByTextRequest
כדי לציין את הפרמטרים האופציונליים של החיפוש.
includedType
מגבילה את התוצאות למקומות שתואמים לסוג שצוין כפי שהוגדר על ידי טבלה א'. אפשר לציין סוג אחד בלבד. למשל:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
אם הערך שלו הוא
true
, מוחזר רק המקומות שפתוחים בפני העסק בזמן שהשאילתה נשלחה. אם הערך הואfalse
, מוחזר כל העסקים ללא קשר לסטטוס הפתיחה. אם מגדירים את הפרמטר הזה ל-false
, יוחזרו מקומות שלא צוינו בהם שעות פתיחה במסד הנתונים של מקומות Google.isStrictTypeFiltering
משתמשים בו עם הפרמטר
includeType
. אם המדיניות מוגדרת לערךtrue
, יוחזרו רק מקומות שתואמים לסוגים שצוינו ב-includeType
. אם הערך הוא False, ברירת המחדל היא התשובה יכולה להכיל מקומות שלא תואמים לסוגים שצוינו.locationBias
מציין את האזור לחיפוש. המיקום הזה משמש כהטיה כך שיוחזר תוצאות מסביב למיקום שצוין, כולל תוצאות מחוץ לאזור שצוין.
אפשר לציין את
locationRestriction
או אתlocationBias
, אבל לא את שתי העמודות. אפשר להתייחס ל-locationRestriction
כאל ציון של האזור שבו התוצאות צריכות להיות, ו-locationBias
הוא ציון האזור שבו התוצאות צריכות להיות קרובות אבל הן יכולות להיות מחוץ לאזור.צריך לציין את האזור כאזור תצוגה מלבני או כעיגול.
מעגל מוגדר לפי נקודת המרכז והרדיוס במטרים. הרדיוס חייב להיות בין 0.0 ל-50,000.0, כולל. רדיוס ברירת המחדל הוא 0.0. למשל:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
מלבן הוא אזור תצוגה של קווי אורך ורוחב, והוא מיוצג בשתי נקודות באלכסון עם מספר נמוך וגבוה באלכסון. הנקודה הנמוכה מסמנת את הפינה הדרום-מערבית של המלבן, והנקודה הגבוהה מייצגת את הפינה הצפון-מזרחית של המלבן.
אזור תצוגה נחשב לאזור סגור, כלומר הוא כולל את התחום שלו. גבולות הרוחב חייבים להיות בין -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
, טווח קו הרוחב ריק.
- אם
locationRestriction
מציין את האזור לחיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין. הגדרת האזור כאזור תצוגה מלבני. אפשר לקרוא מידע נוסף על הגדרת אזור התצוגה בתיאור של
locationBias
.אפשר לציין את
locationRestriction
או אתlocationBias
, אבל לא את שתי העמודות. אפשר להתייחס ל-locationRestriction
כאל ציון של האזור שבו התוצאות צריכות להיות, ו-locationBias
הוא ציון האזור שבו התוצאות צריכות להיות קרובות אבל הן יכולות להיות מחוץ לאזור.-
maxResultCount
מציין את המספר המקסימלי של תוצאות של מקומות שצריך להחזיר. חייב להיות בין 1 ל-20 (ברירת מחדל) כולל.
minRating
הגבלת התוצאות רק למשתמשים שדירוג המשתמשים הממוצע שלהם גדול מהגבלה זו או שווה לה. הערכים חייבים להיות בין 0.0 ל-5.0 (כולל) במרווחים של 0.5. לדוגמה: 0, 0.5, 1.0, ... , 5.0 כולל. הערכים מעוגלים כלפי מעלה עד ל-0.5 הקרוב ביותר. לדוגמה, ערך של 0.6 מבטל את כל התוצאות עם דירוג שנמוך מ-1.0.
-
priceLevels
הגבלת החיפוש למקומות שמסומנים ברמות מחירים מסוימות. ברירת המחדל היא לבחור את כל רמות המחירים.
מציינים מערך של אחד או יותר מהערכים שהוגדרו על ידי
PriceLevel
.למשל:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
מציין איך התוצאות מדורגות בתשובה על סמך סוג השאילתה:
- לשאילתה שמסווגת לפי קטגוריות, כמו "מסעדות בתל אביב",
ברירת המחדל היא
.relevance
(דירוג התוצאות לפי רלוונטיות החיפוש). אפשר להגדיר אתrankPreference
לערך.relevance
או לערך.distance
(דירוג התוצאות לפי מרחק). - בשאילתה ללא קטגוריות, כמו 'Mountain View, CA', מומלץ
להשאיר את
rankPreference
לא מוגדר.
- לשאילתה שמסווגת לפי קטגוריות, כמו "מסעדות בתל אביב",
ברירת המחדל היא
regionCode
קוד האזור שמשמש לעיצוב התשובה, מוגדר כערך של קוד CLDR בן שני תווים. לפרמטר הזה יכולה להיות גם אפקט הטיה על תוצאות החיפוש. אין ערך ברירת מחדל.
אם שם המדינה בשדה הכתובת בתשובה תואם לקוד האזור, קוד המדינה לא יופיע בכתובת.
רוב קודי ה-CLDR זהים לקודי ISO 3166-1, עם כמה יוצאים מן הכלל. לדוגמה, הדומיין ccTLD של בריטניה הוא 'uk' (.co.uk) ואילו קוד ISO 3166-1 הוא 'gb' (טכנית לישות 'בריטניה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לחוק הרלוונטי.
הצגת ייחוס באפליקציה
כשמוצג באפליקציה מידע שהתקבל מ-GMSPlacesClient
, כמו תמונות וביקורות, האפליקציה צריכה להציג גם את המאפיינים הנדרשים.
לדוגמה, המאפיין reviews
של האובייקט GMSPlacesClient
מכיל מערך של עד חמישה אובייקטים של GMSPlaceReview
. כל אובייקט GMSPlaceReview
יכול להכיל ייחוס וייחוס של מחברים.
אם הביקורת מוצגת באפליקציה, צריך גם להציג את הקרדיט או את השיוך למחבר.
מידע נוסף זמין במאמר שיוכים.