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

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

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

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

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

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

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

  צריך לציין אחד או יותר מהשדות הבאים:

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

    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

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

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

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

• includedType

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

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

• isOpenNow

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

• 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

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

למידע נוסף, עיינו במשאבי העזרה בנושא שיוכים.