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

בחירת פלטפורמה: Android iOS JavaScript Web Service

מפתחים באזור הכלכלי האירופי (EEA)

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

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

‫"10 High Street, UK" או "123 Main Street, US" יש כמה רחובות שנקראים High Street בבריטניה, וכמה רחובות שנקראים Main Street בארה"ב. השאילתה לא מחזירה תוצאות רצויות אלא אם מוגדרת הגבלת מיקום.
‫"Chain restaurant New York" ‏(מסעדה בסניף בניו יורק) כמה מיקומים של 'מסעדה ברשת' בניו יורק; לא צוינה כתובת רחוב או אפילו שם רחוב.
‪"10 High Street, Escher UK" or "123 Main Street, Pleasanton US" יש רק רחוב אחד בשם High Street בעיר אֶשֶר בבריטניה, ורק רחוב אחד בשם Main Street בעיר פלזנטון בקליפורניה, ארה"ב.
‪"UniqueRestaurantName New York" יש רק מקום אחד בניו יורק עם השם הזה, ולא צריך לציין כתובת כדי להבדיל ביניהם.
‫"pizza restaurants in New York" (מסעדות פיצה בניו יורק) השאילתה הזו מכילה את הגבלת המיקום שלה, ו'פיצריות' הוא סוג מקום מוגדר היטב. היא מחזירה כמה תוצאות.
"+1 514-670-8700"

השאילתה הזו מכילה מספר טלפון. היא מחזירה כמה תוצאות של מקומות שמשויכים למספר הטלפון הזה.

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

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

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

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

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

Places Swift SDK

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
}

Swift

// 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)

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.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;
      }
    }
  }
];

תשובות לחיפוש טקסט

ה-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

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

תגובה אחת (isOpenWithRequest)

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

שפה הערך אם הפריט פתוח ערך אם העסק סגור ערך אם הסטטוס לא ידוע
Places Swift true false nil
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown

חיוב על isOpenWithRequest

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

דוגמה: יצירת בקשת GMSPlaceIsOpenWithRequest

בדוגמה הבאה מוצג אופן ההגדרה של GMSPlaceIsOpenWithRequest בתוך אובייקט GMSPlace קיים.

Places Swift SDK

        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
        }

Swift

    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
        }
      }

Objective-C

          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
            }
          }];

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

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

  • רשימת השדות

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

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

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

    • השדות הבאים מפעילים את Text Search Essentials ID Only SKU:

      GMSPlacePropertyPlaceID

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

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyName
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

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

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

  • textQuery

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

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

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

  • includedType

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

    • let request = SearchByTextRequest()
      request.includedType = "bar"
    • let request = SearchByTextRequest()
      request.includedType = "pharmacy"

  • isOpenNow

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

  • isStrictTypeFiltering

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

  • locationBias

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

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

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

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

      let request = SearchByTextRequest()
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.

    לדוגמה:

        let request = SearchByTextRequest()
    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    מציינים איך התוצאות מדורגות בתגובה לפי סוג השאילתה:

    • עבור שאילתה קטגורית כמו 'מסעדות בניו יורק', .relevance (דירוג התוצאות לפי הרלוונטיות לחיפוש) היא ברירת המחדל. אפשר להגדיר את rankPreference ל-.relevance או ל-.distance (דירוג התוצאות לפי מרחק).
    • לשאילתה לא קטגורית כמו 'מאונטיין ויו, קליפורניה', מומלץ להשאיר את rankPreference ללא הגדרה.

  • regionCode

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

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

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

  • shouldIncludePureServiceAreaBusinesses

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

    לדוגמה:

    Places Swift SDK

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses = true

    Swift

    let request = SearchByTextRequest()
request.shouldIncludePureServiceAreaBusinesses: true

    Objective-C

    GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
request.shouldIncludePureServiceAreaBusinesses = YES;

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

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

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

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