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

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

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

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

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

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

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

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

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

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

Places Swift SDK

let restriction = GMSPlaceRectangularLocationOption(
      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;
      }
    }
  }
];

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

‫Text Search API מחזיר מערך של התאמות בצורת אובייקטים מסוג GMSPlace, עם אובייקט GMSPlace אחד לכל מקום תואם.

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

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

ה-method הזו מקבלת ארגומנט אחד מסוג GMSPlaceIsOpenWithRequest שמכיל:

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

תגובה אחת (isOpenWithRequest)

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

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

חיוב על isOpenWithRequest

דוגמה: שליחת בקשה מסוג 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
            }
          }];

חלוקה לדפים

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

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

Swift

public struct PlaceSearchPagination {
  public var pageSize: Int
  public var hasNextPage: Bool
  public func fetchNextPage() async -> SearchByTextResponse
}

public struct SearchByTextResponse {
  public var pagination: PlaceSearchPagination?
  public var places: [Place]?
  public var error: PlaceError?
}

PlacesClient.swift
public func searchByText(with request: SearchByTextRequest) async -> SearchByTextResponse

let searchByTextRequest = SearchByTextRequest(textQuery: "restaurants",
    placeProperties: [PlaceProperty.displayName],
    locationBias: CircularCoordinateRegion(center: CLLocationCoordinate2D(latitude: 0, longitude: 0), radius: 100))

searchByTextRequest.maxResultCount = 10

var searchByTextResponse = await PlacesClient.shared.searchByText(with: searchByTextRequest)
print("Found \(searchByTextResponse.places.count) places")

searchByTextResponse.pagination.pageSize = 20

// Continue making requests until no more results are found in pagination object
while searchByTextResponse.pagination.hasNextPage {
    searchByTextResponse = await searchByTextResponse.pagination.fetchNextPage()
    print("Found \(searchByTextResponse.places.count) places")
}

Objective-C

GMSPlaceSearchByTextRequest *searchByTextRequest = [[GMSPlaceSearchByTextRequest alloc]
    initWithTextQuery: @"restaurants"
    placeProperties: @[GMSPlacePropertyAll]];

searchByTextRequest.maxResultCount = 10;

__block void (^recursiveCallback)(GMSPlaceSearchByTextResponse *, NSError *);
recursiveCallback = ^(GMSPlaceSearchByTextResponse * response, NSError* error) {
    NSLog(@"Found %d places", response.places.count);
    if (response.pagination.hasNextPage) {
      [response.pagination fetchNextPageWithCompletion:recursiveCallback];
   }
};
[GMSPlacesClient.sharedClient searchByTextWithRequest:searchByTextRequest  
                                           completion:recursiveCallback];

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

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

  • רשימת שדות

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

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

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

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

      GMSPlacePropertyPlaceID

      רשימה מלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

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

      הרשימה המלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

      רשימה מלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

    • השדות הבאים מפעילים את מק"ט חיפוש הטקסט של 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 ל-50,000.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

    מציין אזור לחיפוש. לא יוחזרו תוצאות מחוץ לאזור שצוין. מציינים את האזור כ-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.

    לדוגמה:

        let request = SearchByTextRequest()
    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 (מבחינה טכנית, עבור הישות "הממלכה המאוחדת של בריטניה הגדולה וצפון אירלנד"). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

  • shouldIncludePureServiceAreaBusinesses

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

    לדוגמה:

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

מידע נוסף מופיע במאמר בנושא שיוך (Attribution).