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

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

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

בקשות של חיפוש בסביבה (חדש)

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

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

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

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

• רשימת השדות

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

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

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

    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 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 כדי לציין את הפרמטרים האופציונליים של החיפוש.

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

  מאפשר לציין רשימה של סוגים מתוך types Table A שמשמשים לסינון תוצאות החיפוש. אפשר לציין עד 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.