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

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

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

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

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

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

  • רשימת שדות

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

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

    • השדות הבאים מפעילים את מהדורת 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

      הרשימה המלאה של השדות והמקט"ים שמשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

    • השדות הבאים מפעילים את חיפוש בסביבה 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

      רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

      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

      רשימה מלאה של השדות והמק"טים המשויכים אליהם מופיעה במאמר בנושא שדות של נתוני מקומות (חדש).

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

    כדי להגדיר את הפרמטר של הסוגים שלא נכללים, צריך להפעיל את ה-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, עם כמה חריגים בולטים. לדוגמה, ה-ccTLD של בריטניה הוא uk (‎.co.uk), אבל קוד ISO 3166-1 שלה הוא gb (טכנית, עבור הישות 'בריטניה וצפון אירלנד'). הפרמטר יכול להשפיע על התוצאות בהתאם לדין החל.

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

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

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

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