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

בחירת פלטפורמה: 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 בתגובה.

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

    סוגי הפריטים הכלולים

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

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

    סוגי מודעות מוחרגים

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

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

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

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

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

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

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

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

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

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

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