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

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

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

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

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

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

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

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

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

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

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

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

  • רשימת השדות

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

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

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

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
          * משתמשים במקום ב-Place.Field.NAME, שהוצא משימוש.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * יש להשתמש במקום Place.Field.ICON_URL, שהוצא משימוש.
      Place.Field.ID
      Place.Field.LAT_LNG
      Place.Field.PHOTO_METADATAS
      Place.Field.PLUS_CODE
      Place.Field.PRIMARY_TYPE
      Place.Field.PRIMARY_TYPE_DISPLAY_NAME
      Place.Field.RESOURCE_NAME
      Place.Field.TYPES
      Place.Field.UTC_OFFSET
      Place.Field.VIEWPORT
      Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • השדות הבאים מפעילים את מהדורת Nearby Search Enterprise:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * אפשר להשתמש במקום ב-Place.Field.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.USER_RATINGS_TOTAL הוצא משימוש, ולכן צריך להשתמש ב-
      Place.Field.WEBSITE_URI

    • השדות הבאים מפעילים את Nearby Search Enterprise Plus SKU:

      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);

  • הגבלת מיקום

    ‫A LocationRestriction אובייקט שמגדיר את האזור לחיפוש שצוין כמעגל, שמוגדר על ידי נקודת מרכז ורדיוס במטרים. הערך של הרדיוס צריך להיות גדול מ-0.0 וקטן מ-50,000.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 מופיעה בקטע בקשות לחיפוש בקרבת מקום (חדש).

    סוגים כלולים

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • העדפת דירוג

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

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

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

  • קוד אזור

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

    אם שם המדינה בשדה FORMATTED_ADDRESS בתשובה תואם לערך regionCode, קוד המדינה מושמט מהשדה FORMATTED_ADDRESS.

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

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

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

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

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