חיפוש טקסט

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

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

"10 High Street, UK" או "123Main Street, US"	מספר "רחובות" בבריטניה; מספר "רחובות ראשיים" בארה"ב. השאילתה לא מחזירה תוצאות רצויות, אלא אם מוגדרת הגבלת מיקום.
"רשת מסעדות תל אביב"	כמה מיקומים של 'רשת מסעדות' בניו יורק, ללא שם רחוב ואפילו שם רחוב.
"10 High Street, Escher UK" או "123 הדרך הראשית, חיפה"	רק "רחוב גבוה" אחד בעיר אשר בבריטניה; רק "רחוב ראשי" אחד בעיר פלסנטון בארה"ב.
"UniqueRestaurantName New York"	רק בית עסק אחד בשם זה בניו יורק; אין צורך בכתובת כדי להבדיל בין אלה.
"פיצריות בתל אביב"	השאילתה הזו מכילה את הגבלת המיקום שלה, ו "מסעדות פיצה" הוא סוג מקום מוגדר היטב. היא מחזירה מספר תוצאות.
"[phone]"	השאילתה הזו מכילה מספר טלפון. הוא יחזיר מספר תוצאות עבור מקומות שמשויכים למספר הטלפון הזה. הערה: כדי לקבל את התוצאות הטובות ביותר כשמחפשים מספר טלפון, יש לכלול את קוד המדינה ואחריה רווח, ולהגדיר את הפרמטר regionCode כך שיתאים לקוד המדינה.

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

בקשה לחיפוש טקסט ב-Place SDK ל-iOS (חדש) תתבצע באמצעות הטופס הבא:

Swift

func testPlaceSearchByTextRequestGMPSRequestCreationWithProperties() {
  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)
  )
}

Objective-C

- (void)testPlaceSearchByTextRequestGMPSRequestCreationWithProperties {
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);
}

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

• רשימת שדות

  יש לציין אילו מאפיינים של נתוני מקום להחזיר. מעבירים רשימה של נכסים מסוג 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, GMSPlacePropertyServesBeer, GMSPlacePropertyServesBreakfast, GMSPlacePropertyServesBrunch, GMSPlacePropertyServesDinner, GMSPlacePropertyServesLunch, GMSPlacePropertyServesVegetarianFood, GMSPlacePropertyServesWine, GMSPlacePropertyTakeout

• textQuery

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

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

• includedType

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

  • request.includedType = "bar"
  • request.includedType = "pharmacy"
  הערה: הערכים בטבלה ב' מוחזרים רק בתגובה. לא ניתן להשתמש בערכים בטבלה ב' כמסנן.

• isOpenNow

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

• isStrictTypeFiltering

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

• locationBias

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

  אפשר לציין locationRestriction או locationBias, אבל לא את שתיהן. אפשר להתייחס ל-locationRestriction כאל האזור שבו התוצאות חייבות להיות ועל locationBias לציון האזור שהתוצאות חייבות להיות בקרבתו, אבל יכולות להיות מחוץ לאזור.

  הערה: אם משמיטים את locationBias וגם locationRestriction, ה-API משתמש בתעדוף לפי IP כברירת מחדל. בתעדוף לפי IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.
  הערה: אפשר לבטל את הפרמטר locationBias אם textQuery מכיל מיקום מפורש כמו Market in Barcelona. במקרה כזה, המערכת תתעלם מ-locationBias.

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

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

  הערה: אם משמיטים את locationBias וגם locationRestriction, ה-API משתמש בתעדוף לפי IP כברירת מחדל. בתעדוף לפי IP, ה-API משתמש בכתובת ה-IP של המכשיר כדי להטות את התוצאות.

• 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.

  הערה: אסור להשתמש ב-PRICE_LEVEL_FREE במסגרת בקשה. הוא משמש רק לאכלוס התשובה.

  למשל:

  request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

• rankPreference

  מציין את אופן דירוג התוצאות בתשובה. ה-API משתמש ב-RELEVANCE כברירת מחדל, במקרים הרלוונטיים. לדוגמה, בתגובה לשאילתה כמו "מסעדות בתל אביב", ברירת המחדל תהיה RELEVANCE. עבור שאילתות גיאוגרפיות, כמו "Mountain View, CA", או שאילתות מסוג אחר, לא תחול ברירת מחדל והתוצאות יופיעו לפי הסדר שבו הן הוחזרו על ידי הקצה העורפי.

  הערכים כוללים:

  • .distance: דירוג התוצאות לפי מרחק.
  • .relevance: דירוג התוצאות לפי רלוונטיות.

• regionCode

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

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

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

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

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