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

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

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

"10 High Street, UK" או "123Main Street, US" מספר "רחובות" בבריטניה; מספר "רחובות ראשיים" בארה"ב. השאילתה לא מחזירה תוצאות רצויות, אלא אם מוגדרת הגבלת מיקום.
"רשת מסעדות תל אביב" כמה מיקומים של 'רשת מסעדות' בניו יורק, ללא שם רחוב ואפילו שם רחוב.
"10 High Street, Escher UK" או "123 הדרך הראשית, חיפה" רק "רחוב גבוה" אחד בעיר אשר בבריטניה; רק "רחוב ראשי" אחד בעיר פלסנטון בארה"ב.
"UniqueRestaurantName New York" רק בית עסק אחד בשם זה בניו יורק; אין צורך בכתובת כדי להבדיל בין אלה.
"פיצריות בתל אביב" השאילתה הזו מכילה את הגבלת המיקום שלה, ו "מסעדות פיצה" הוא סוג מקום מוגדר היטב. היא מחזירה מספר תוצאות.
"+1 514-670-8700"

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

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

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

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

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

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

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

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

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

      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

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

למידע נוסף, עיינו במסמכי התיעוד בנושא שיוך (Attribution).