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

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

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