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

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

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

איך מקבלים רשימה של מקומות באמצעות חיפוש טקסט

שולחים בקשה לחיפוש טקסט על ידי קריאה ל-GMSPlacesClient searchByTextWithRequest:, מעבירים אובייקט GMSPlaceSearchByTextRequest שמגדיר את פרמטרי הבקשה וכן שיטה להפעלה חוזרת (callback) מסוג GMSPlaceSearchByTextResultCallback לטיפול בתגובה.

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

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

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

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

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
  }
  placeResults = results
}

GMSPlacesClient.shared().searchByText(with: request, callback: callback)

// 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.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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 (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

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 אחד לכל מקום תואם.

אחזור הסטטוס 'פתוח'

האובייקט GMSPlacesClient מכיל פונקציית חבר בשם isOpenWithRequest (isOpenRequest ב-Swift ו-isPlaceOpenRequest ב-GooglePlacesSwift) שמחזירה תשובה שמציינת אם המקום פתוח כרגע, על סמך השעה שצוינה בקריאה.

לשיטה הזו יש ארגומנטים יחידים מסוג GMSPlaceIsOpenWithRequest שמכילים:

• אובייקט GMSPlace או מחרוזת שציינו בה מזהה מקום. מידע נוסף על יצירת אובייקט Place עם השדות הנדרשים זמין במאמר פרטי מקום.
  
• אובייקט NSDate (Obj-C) או Date (Swift) אופציונלי שקובע את המועד שרוצים לבדוק. אם לא מציינים שעה, ברירת המחדל היא 'עכשיו'.
• שיטה GMSPlaceOpenStatusResponseCallback לטיפול בתגובה.
>

כדי להשתמש בשיטה GMSPlaceIsOpenWithRequest, צריך להגדיר את השדות הבאים באובייקט GMSPlace:

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

אם השדות האלה לא יסופקו באובייקט Place, או אם מעבירים מזהה מקום, השיטה תשתמש ב-GMSPlacesClient GMSFetchPlaceRequest: כדי לאחזר אותם.

תגובה אחת (isOpenWithRequest)

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

חיוב עבור isOpenWithRequest

• השדות GMSPlacePropertyUTCOffsetMinutes ו-GMSPlacePropertyBusinessStatus מחויבים במסגרת מק"ט הנתונים הבסיסיים. שאר שעות הפתיחה יחויבו במסגרת המק"ט פרטי המקום (מתקדם).
• אם השדות האלה כבר קיימים באובייקט GMSPlace מבקשה קודמת, לא תחויבו שוב.

דוגמה: שליחת בקשה מסוג GMSPlaceIsOpenWithRequest

    let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil)
      GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in
        if let error = error {
          // Handle Error
        }
        switch response.status {
          case .open:
            // Handle open
          case .closed:
            // Handle closed
          case .unknown:
            // Handle unknown
        }
      }
        

          GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil];
  
          [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) {
            if (error) {
              // Handle error
            }
  
            switch (response.status) {
              case GMSPlaceOpenStatusOpen:
                // Handle open
              case GMSPlaceOpenStatusClosed:
                // Handle closed
              case GMSPlaceOpenStatusUnknown:
                // Handle unknown
            }
          }];
          

          let isOpenRequest = IsPlaceOpenRequest(place: place)
          switch await placesClient.isPlaceOpen(with: isOpenRequest) {
            case .success(let isOpenResponse):
              switch isOpenResponse.status {
                case true:
                  // Handle open
                case false:
                  // Handle closed
                case nil:
                  // Handle unknown
            case .failure(let placesError):
              // Handle error
          }
          

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

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

• רשימת שדות

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

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

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

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

    GMSPlacePropertyPlaceID, GMSPlacePropertyName

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

    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

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

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

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

• includedType

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

  • request.includedType = "bar"
  • request.includedType = "pharmacy"

• isOpenNow

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

• isStrictTypeFiltering

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

• locationBias

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

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

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

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

    request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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

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

• regionCode

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

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

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

הצגת שיוך באפליקציה

אם האפליקציה מציגה מידע שהתקבל מ-GMSPlacesClient, כמו תמונות וביקורות, צריך להציג בה גם את הקרדיטים הנדרשים.

לדוגמה, המאפיין reviews של האובייקט GMSPlacesClient מכיל מערך של עד חמישה אובייקטים מסוג GMSPlaceReview. כל אובייקט GMSPlaceReview יכול להכיל שיוך לתוכן ושיוכים של מחברים. אם אתם מציגים את הביקורת באפליקציה, עליכם גם להציג את הקרדיט או את הקרדיט של המחבר.

למידע נוסף, קראו את המאמר שיוך.