חיפוש בקרבת מקום (חדש)

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

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

בקשות של חיפוש בקרבת מקום (חדש)

יוצרים בקשת חיפוש בקרבת מקום (חדש) באמצעות קריאה ל-PlacesClient.searchNearby, העברת אובייקט SearchNearbyRequest שמגדיר את הפרמטרים של הבקשה.

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

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

הדוגמה הזו של בקשת החיפוש בקרבת מקום מציינת שהאובייקטים של התגובה Place מכילים את שדות המקום Place.Field.ID ו-Place.Field.NAME לכל אובייקט Place בתוצאות החיפוש. הוא גם מסנן את התשובה כדי להציג רק מקומות מסוג 'מסעדה' ו'בית קפה', אבל לא כולל מקומות מסוג 'פיצה_מסעדה' ו-'american_restaurant'.

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

תגובות של חיפוש בקרבת מקום (חדש)

המחלקה SearchNearbyResponse מייצגת את התגובה לבקשת חיפוש. אובייקט SearchNearbyResponse מכיל:

  • רשימה של Place אובייקטים שמייצגים את כל המקומות התואמים, עם אובייקט Place אחד לכל מקום תואם.
  • כל אובייקט Place מכיל רק את השדות שמוגדרים ברשימת השדות שמועברת בבקשה.

לדוגמה, בבקשה הגדרתם רשימת שדות כך: 

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

המשמעות של רשימת השדות הזו היא שכל אובייקט Place בתשובה מכיל רק את מזהה המקום והשם של כל מקום תואם. לאחר מכן אפשר להשתמש ב-methods Place.getId() ו-Place.getName() כדי לגשת לשדות האלה בכל אובייקט Place.

לדוגמאות נוספות של גישה לנתונים באובייקט Place, ראו גישה לשדות של נתוני אובייקט של Place.

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

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

  • רשימת שדות

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

    צריך לציין אחד או יותר מהשדות הבאים:

    • השדות הבאים מפעילים את Nearby Search (בסיסי):

      Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • השדות הבאים מפעילים את Nearby Search (Advanced) SKU:

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

    • השדות הבאים מפעילים את Nearby Search (Preferred):

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

    כדי להגדיר את הפרמטר של רשימת השדות, קוראים ל-method setPlaceFields() כשמפתחים את האובייקט SearchNearbyRequest.

    בדוגמה הבאה מוגדרת רשימה של שני ערכי שדות כדי לציין שהאובייקט Place שהוחזר בעקבות בקשה מכיל את השדות Place.Field.ID ו-Place.Field.NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

  • הגבלת מיקום

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

    כדי להגדיר את הפרמטר של הגבלת המיקום, כשמפתחים את האובייקט SearchNearbyRequest, קוראים ל-method setLocationRestriction().

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

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

  • סוגים וסוגים ראשיים

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

    למקום אפשר לשייך רק סוג ראשי יחיד מהסוגים טבלה א'. לדוגמה, הסוג הראשי יכול להיות "mexican_restaurant" או "steak_house". אפשר להשתמש ב-includedPrimaryTypes וב-excludedPrimaryTypes כדי לסנן את התוצאות לפי הסוג הראשי של מקום.

    למקום יכולים להיות גם כמה ערכים של סוגים מהסוגים טבלה א' שמשויכים אליו. לדוגמה, מסעדות יכולות להיות מהסוגים הבאים: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". אפשר להשתמש ב-includedTypes וב-excludedTypes כדי לסנן את התוצאות ברשימת הסוגים שמשויכים למקום.

    אם חיפוש מוגדר עם כמה הגבלות סוגים, יוחזרו רק מקומות שעומדים בכל ההגבלות. לדוגמה, אם מציינים את includedTypes = Arrays.asList("restaurant") ואת excludedPrimaryTypes = Arrays.asList("steak_house"), המקומות המוחזרים מספקים שירותים שקשורים ל-"restaurant" אבל לא פועלים בעיקר כ"steak_house".

    דוגמה לאופן השימוש ב-includedTypes וב-excludedTypes מופיעה במאמר בקשות חיפוש בקרבת מקום (חדש).

    הסוגים הכלולים

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

    כדי להגדיר את הפרמטר של הסוגים הכלולים, צריך להפעיל את השיטה setIncludedTypes() כשיוצרים את האובייקט SearchNearbyRequest.

    סוגים מוחרגים

    רשימה של סוגי מקומות מטבלה א' להחרגה מהחיפוש.

    אם מציינים בבקשה גם את includedTypes (כמו "school") וגם את excludedTypes (למשל "primary_school"), התשובה תכלול מקומות שמסווגים בתור "school" אבל לא בתור "primary_school". התגובה כוללת מקומות שתואמים ללפחות אחד מתוך includedTypes ואף אחד מ-excludedTypes.

    אם יש סוגים מתנגשים, כמו סוג שמופיע גם ב-includedTypes וגם ב-excludedTypes, תוחזר שגיאת INVALID_REQUEST.

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

    הסוגים הראשיים הכלולים

    רשימה של סוגים ראשיים של מקומות מטבלה א' שאפשר לכלול בחיפוש.

    כדי להגדיר את הפרמטר של הסוגים הראשיים שכלול, צריך להפעיל את השיטה setIncludedPrimaryTypes() כשיוצרים את האובייקט SearchNearbyRequest.

    סוגים ראשיים שלא נכללים

    רשימה של סוגים ראשיים של מקומות מטבלה א שצריך להחריג מחיפוש.

    אם יש סוגים ראשיים מתנגשים, כמו סוג שמופיע גם ב-includedPrimaryTypes וגם ב-excludedPrimaryTypes, תוחזר שגיאת INVALID_ARGUMENT.

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

  • מספר התוצאות המקסימלי

    מציין את המספר המקסימלי של תוצאות של מקומות שצריך להחזיר. חייב להיות בין 1 ל-20 (ברירת מחדל) כולל.

    כדי להגדיר את הפרמטר של מספר התוצאות המקסימלי, צריך להפעיל את השיטה setMaxResultCount() כשיוצרים את האובייקט SearchNearbyRequest.

  • העדפת דירוג

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

    • POPULARITY (ברירת מחדל) מיון התוצאות לפי הפופולריות שלהן.
    • DISTANCE מיון התוצאות בסדר עולה לפי המרחק שלהן מהמיקום שצוין.

    כדי להגדיר את הפרמטר של העדפת הדירוג, מפעילים את השיטה setRankPreference() כשמפתחים את האובייקט SearchNearbyRequest.

  • קוד אזור

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

    אם שם המדינה בשדה formattedAddress בתשובה תואם ל-regionCode, קוד המדינה לא יופיע ב-formattedAddress.

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

    כדי להגדיר את הפרמטר של קוד האזור, צריך להפעיל את השיטה setRegionCode() כשמפתחים את האובייקט SearchNearbyRequest.

הצגת ייחוס באפליקציה

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

מידע נוסף זמין במאמר מדיניות לגבי Places SDK ל-Android.