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

בחירת פלטפורמה: Android iOS JavaScript שירות אינטרנט

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

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

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

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

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

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

הדוגמה הזו של בקשת חיפוש בקרבת מקום מציינת שהתשובה Place אובייקטים כוללים את שדות המקום Place.Field.ID ו-Place.Field.NAME בכל אחד מהם אובייקט Place בתוצאות החיפוש. הוא גם יסנן את התשובה רק החזרת מקומות מסוג 'מסעדה' ו'בית קפה', אבל לא לכלול מקומות מסוג 'פיצה_מסעדה' ו-"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.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 class מייצג את התגובה מבקשת חיפוש. 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, ראו גישה למקום שדות נתונים של אובייקט.

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

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

  • רשימת שדות

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

    צריך לציין אחד או יותר מהשדות הבאים:

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

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

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

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

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

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, 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.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.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 כדי לסנן את התוצאות ברשימת הסוגים שמשויכים מקום מסוים.

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

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

  • העדפת דירוג

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

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

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

  • קוד אזור

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

    אם שם המדינה בשדה formattedAddress בתשובה תואם את regionCode, קוד המדינה לא צוין ב-formattedAddress.

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

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

הצגת ייחוס באפליקציה

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

למידע נוסף, ראה מדיניות בנושא מקומות SDK עבור ב-Android.