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

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

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

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

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

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

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

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

בבקשת החיפוש בקרבת מקום לדוגמה הזו מצוין שאובייקטי התגובה מסוג Place מכילים את שדות המיקום Place.Field.ID ו-Place.Field.DISPLAY_NAME לכל אובייקט 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.DISPLAY_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 מפורטות במאמר גישה לשדות הנתונים של אובייקט מקום.

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

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

  • רשימת שדות

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

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

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

      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.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI

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

      Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

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

    בדוגמה הבאה מוגדרת רשימה של שני ערכי שדות כדי לציין שהאובייקט Place שמוחזר על ידי בקשה מכיל את השדות Place.Field.ID ו-Place.Field.DISPLAY_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.DISPLAY_NAME);

  • הגבלת מיקום

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

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

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

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

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

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

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

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

    כשמציינים סוג ראשי כללי, כמו "restaurant" או "hotel", התשובה עשויה לכלול מקומות עם סוג ראשי ספציפי יותר מהסוג שצוין. לדוגמה, אפשר לציין שרוצים לכלול את הסוג הראשי "restaurant". התגובה יכולה לכלול מקומות עם סוג ראשי של "restaurant", אבל היא יכולה לכלול גם מקומות עם סוג ראשי ספציפי יותר, כמו "chinese_restaurant" או "seafood_restaurant".

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

    כדי להגדיר את הפרמטר של מספר התוצאות המקסימלי, צריך לקרוא ל-method‏ setMaxResultCount() בזמן היצירה של האובייקט SearchNearbyRequest.

  • העדפת דירוג

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

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

    כדי להגדיר את הפרמטר של העדפת הדירוג, צריך לבצע קריאה ל-method‏ setRankPreference() בזמן היצירה של האובייקט SearchNearbyRequest.

  • קוד אזור

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

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

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

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

הצגת שיוך באפליקציה

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

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