आस-पास की जगहों की जानकारी (नया)

प्लैटफ़ॉर्म चुनें: Android iOS JavaScript वेब सेवा

आस-पास खोजने की सुविधा (नया) के अनुरोध में, सर्कल के तौर पर तय किए गए इलाके को इनपुट के तौर पर लिया जाता है. सर्कल के बीच के पॉइंट के अक्षांश और देशांतर निर्देशांक और मीटर में त्रिज्या से सर्कल तय किया जाता है. रिक्वेस्ट करने पर, खोज के लिए तय किए गए इलाके में, मैच होने वाली जगहों की सूची दिखती है. हर जगह को Place ऑब्जेक्ट से दिखाया जाता है.

डिफ़ॉल्ट रूप से, खोज के लिए तय किए गए इलाके में सभी तरह की जगहें शामिल होती हैं. आपके पास जवाब को फ़िल्टर करने का विकल्प होता है. इसके लिए, जगह के टाइप की सूची दी जा सकती है, ताकि जवाब में उन्हें शामिल किया जा सके या बाहर रखा जा सके. उदाहरण के लिए, जवाब में सिर्फ़ "रेस्टोरेंट", "बेकरी", और "कैफ़े" जैसी जगहों को शामिल करने के लिए कहा जा सकता है. इसके अलावा, "स्कूल" जैसी सभी जगहों को बाहर रखा जा सकता है.

ध्यान दें: आस-पास खोजने की सुविधा (नई), Android 3.5.0 और इसके बाद के वर्शन के लिए, Places SDK टूल में उपलब्ध है. ज़्यादा जानकारी के लिए, SDK टूल का वर्शन चुनना लेख पढ़ें. 4.0.0 वर्शन में जोड़े गए Kotlin एपीआई इस्तेमाल करने के बारे में ज़्यादा जानकारी के लिए, रेफ़रंस की खास जानकारी देखें.

आस-पास की जगहों की जानकारी (नया) के अनुरोध

PlacesClient.searchNearby को कॉल करके, आस-पास की जगहों की खोज (नया) का अनुरोध करें. इसके लिए, अनुरोध के पैरामीटर तय करने वाला SearchNearbyRequest ऑब्जेक्ट पास करें.

SearchNearbyRequest ऑब्जेक्ट, अनुरोध के लिए सभी ज़रूरी और वैकल्पिक पैरामीटर की जानकारी देता है. ज़रूरी पैरामीटर में ये शामिल हैं:

• Place ऑब्जेक्ट में दिखाए जाने वाले फ़ील्ड की सूची. इसे फ़ील्ड मास्क भी कहा जाता है. अगर आपने फ़ील्ड की सूची में कम से कम एक फ़ील्ड नहीं बताया है या फ़ील्ड की सूची को शामिल नहीं किया है, तो कॉल में गड़बड़ी का मैसेज दिखेगा.
• खोज के लिए चुने गए इलाके पर पाबंदी. इसे अक्षांश/देशांतर के जोड़े और मीटर में दायरे की वैल्यू के तौर पर तय किया जाता है.

आस-पास की जगहों को खोजने के अनुरोध के इस उदाहरण से पता चलता है कि रिस्पॉन्स के Place ऑब्जेक्ट में, खोज के नतीजों में मौजूद हर Place ऑब्जेक्ट के लिए, जगह के फ़ील्ड Place.Field.ID और Place.Field.DISPLAY_NAME शामिल होते हैं. यह रिस्पॉन्स को फ़िल्टर भी करता है, ताकि सिर्फ़ "रेस्टोरेंट" और "कैफ़े" टाइप की जगहें दिखें. हालांकि, "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();
    });

ध्यान दें: PlacesClient को शुरू करने के बारे में ज़्यादा जानकारी के लिए, Places API क्लाइंट को शुरू करना देखें.

किसी भी अनुरोध क्लास (उदाहरण के लिए, FetchPlaceRequest) के अनुरोध को रद्द करने के लिए, CancellationToken का इस्तेमाल किया जा सकता है. अनुरोध को रद्द करने की कोशिश पूरी तरह से सफल नहीं हो सकती. सदस्यता रद्द करने का अनुरोध करने के बाद, आपको कोई जवाब नहीं मिलेगा. रद्द करने का टोकन जारी करने से, यह गारंटी नहीं मिलती कि कोई अनुरोध रद्द हो जाएगा. साथ ही, अगर कोई जवाब नहीं मिलता है, तब भी आपसे अनुरोध के लिए शुल्क लिया जा सकता है.

आस-पास की जगहों की जानकारी (नया) के जवाब

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 ऑब्जेक्ट में इन फ़ील्ड को ऐक्सेस करने के लिए, Place.getId() और Place.getName() तरीकों का इस्तेमाल किया जा सकता है.

Place ऑब्जेक्ट में डेटा ऐक्सेस करने के ज़्यादा उदाहरणों के लिए, जगह के ऑब्जेक्ट के डेटा फ़ील्ड ऐक्सेस करना लेख पढ़ें.

ज़रूरी पैरामीटर

खोज के लिए ज़रूरी पैरामीटर तय करने के लिए, SearchNearbyRequest ऑब्जेक्ट का इस्तेमाल करें.

• फ़ील्ड की सूची

  किसी जगह की जानकारी का अनुरोध करते समय, आपको फ़ील्ड मास्क के तौर पर, जगह के लिए Place ऑब्जेक्ट में दिखाने के लिए डेटा तय करना होगा. फ़ील्ड मास्क तय करने के लिए, Place.Field से SearchNearbyRequest ऑब्जेक्ट में वैल्यू का कलेक्शन पास करें. फ़ील्ड मास्किंग, डिज़ाइन का एक अच्छा तरीका है. इससे यह पक्का किया जा सकता है कि आपने ज़रूरत से ज़्यादा डेटा का अनुरोध न किया हो. इससे, प्रोसेसिंग में लगने वाले समय और बिलिंग शुल्कों से बचा जा सकता है.

  इनमें से एक या उससे ज़्यादा फ़ील्ड डालें:

  • ये फ़ील्ड, आस-पास खोजने की सुविधा के लिए उपलब्ध Pro 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.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

  • ये फ़ील्ड, आस-पास खोज की सुविधा के लिए एंटरप्राइज़ SKU को ट्रिगर करते हैं:

    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
    
    अब काम न करने वाले फ़ील्ड:Places SDK for Android के 4.0 वर्शन में, Place.Field.PHONE_NUMBER और Place.Field.USER_RATINGS_TOTAL फ़ील्ड का इस्तेमाल नहीं किया जा सकता. इसके बजाय, Place.Field.INTERNATIONAL_PHONE_NUMBER और Place.USER_RATING_COUNT का इस्तेमाल करें.

  • ये फ़ील्ड, आस-पास खोज की सुविधा के लिए, 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
  ध्यान दें: Android के लिए Places SDK टूल के वर्शन 4.0 में, जगह के कई डेटा फ़ील्ड का इस्तेमाल बंद कर दिया गया है. साथ ही, नए फ़ील्ड जोड़े गए हैं. ज़्यादा जानकारी के लिए, Places SDK for Android 4.0 में जगह के नए डेटा फ़ील्ड पर माइग्रेट करना लेख पढ़ें.

  फ़ील्ड की सूची वाले पैरामीटर को सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय, setPlaceFields() विधि को कॉल करें.

  इस उदाहरण में, दो फ़ील्ड वैल्यू की सूची दी गई है. इससे यह पता चलता है कि किसी अनुरोध से मिले 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 दिखेगा.

  जगह की पाबंदी वाला पैरामीटर सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setLocationRestriction() वाला तरीका इस्तेमाल करें.

ज़रूरी नहीं पैरामीटर

खोज के लिए वैकल्पिक पैरामीटर तय करने के लिए, SearchNearbyRequest ऑब्जेक्ट का इस्तेमाल करें.

• टाइप और प्राइमरी टाइप

  इससे, खोज के नतीजों को फ़िल्टर करने के लिए इस्तेमाल की जाने वाली टेबल A के टाइप की सूची तय की जा सकती है. पाबंदी के हर टाइप की कैटगरी में, ज़्यादा से ज़्यादा 50 टाइप शामिल किए जा सकते हैं.

  ध्यान दें: टेबल B में मौजूद वैल्यू, सिर्फ़ जवाब में दिखती हैं. टेबल B में मौजूद वैल्यू का इस्तेमाल, फ़िल्टर के तौर पर नहीं किया जा सकता.

  किसी जगह के लिए, टेबल A में मौजूद टाइप में से सिर्फ़ एक प्राइमरी टाइप हो सकता है. उदाहरण के लिए, प्राइमरी टाइप "mexican_restaurant" या "steak_house" हो सकता है. किसी जगह के प्राइमरी टाइप के हिसाब से नतीजों को फ़िल्टर करने के लिए, includedPrimaryTypes और excludedPrimaryTypes का इस्तेमाल करें.

  किसी जगह के लिए, टाइप से जुड़ी टेबल A में मौजूद एक से ज़्यादा टाइप की वैल्यू भी हो सकती हैं. उदाहरण के लिए, किसी रेस्टोरेंट के लिए ये टाइप इस्तेमाल किए जा सकते हैं: "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, includedPrimaryTypes, और excludedPrimaryTypes को शामिल नहीं किया जाता है, तो खोज के नतीजों में, जगह की पाबंदी के दायरे में आने वाली सभी जगहें दिखती हैं.

  includedTypes और excludedTypes का इस्तेमाल करने का उदाहरण देखने के लिए, आस-पास की जगहें खोजने की सुविधा (नया) के अनुरोध देखें.

  शामिल किए गए टाइप

  टेबल A में मौजूद, खोजने के लिए जगहों के टाइप की सूची. अगर इस पैरामीटर को शामिल नहीं किया जाता है, तो सभी तरह की जगहें दिखती हैं.

  शामिल किए गए टाइप पैरामीटर को सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setIncludedTypes() तरीके को कॉल करें.

  शामिल नहीं किए गए टाइप

  टेबल A में मौजूद जगहों के टाइप की सूची, जिन्हें खोज के नतीजों में नहीं दिखाना है.

  अगर अनुरोध में includedTypes (जैसे, "school") और excludedTypes (जैसे, "primary_school") दोनों की जानकारी दी जाती है, तो रिस्पॉन्स में ऐसी जगहें शामिल होती हैं जिन्हें "school" कैटगरी में रखा गया है, लेकिन "primary_school" में नहीं. जवाब में ऐसी जगहें शामिल हैं जो includedTypes में से कम से कम एक और excludedTypes में से किसी भी से मैच करती हैं.

  अगर कोई ऐसा टाइप है जो includedTypes और excludedTypes, दोनों में दिखता है, तो INVALID_REQUEST गड़बड़ी का मैसेज दिखता है.

  बाहर रखे गए टाइप पैरामीटर को सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setExcludedTypes() तरीके को कॉल करें.

  शामिल किए गए प्राइमरी टाइप

  टेबल A में मौजूद, मुख्य जगहों के टाइप की सूची, ताकि उन्हें खोज में शामिल किया जा सके.

  शामिल किए गए प्राइमरी टाइप पैरामीटर को सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setIncludedPrimaryTypes() तरीके को कॉल करें.

  बाहर रखे गए प्राइमरी टाइप

  टेबल A में मौजूद, मुख्य जगहों के टाइप की सूची, जिसे खोज के नतीजों से बाहर रखना है.

  अगर कोई मुख्य टाइप एक-दूसरे से मेल नहीं खाता है, जैसे कि includedPrimaryTypes और excludedPrimaryTypes, तो INVALID_ARGUMENT गड़बड़ी का मैसेज दिखता है.

  बाहर रखे गए प्राइमरी टाइप पैरामीटर को सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setExcludedPrimaryTypes() तरीके को कॉल करें.

• ज़्यादा से ज़्यादा नतीजों की संख्या

  जगह के ज़्यादा से ज़्यादा कितने नतीजे दिखाने हैं, यह तय करता है. यह वैल्यू 1 से 20 (डिफ़ॉल्ट) के बीच होनी चाहिए.

  नतीजों की ज़्यादा से ज़्यादा संख्या का पैरामीटर सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setMaxResultCount() तरीका कॉल करें.

• रैंक की प्राथमिकता

  इस्तेमाल की जाने वाली रैंकिंग का टाइप. अगर इस पैरामीटर को शामिल नहीं किया जाता है, तो नतीजों को लोकप्रियता के हिसाब से रैंक किया जाता है. इनमें से कोई एक हो सकता है:

  • POPULARITY (डिफ़ॉल्ट) नतीजों को उनकी लोकप्रियता के हिसाब से क्रम में लगाता है.
  • DISTANCE तय की गई जगह से दूरी के हिसाब से, नतीजों को बढ़ते क्रम में क्रमबद्ध करता है.

  रैंक प्राथमिकता पैरामीटर सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setRankPreference() तरीके को कॉल करें.

• क्षेत्र कोड

  रिस्पॉन्स को फ़ॉर्मैट करने के लिए इस्तेमाल किया जाने वाला क्षेत्र कोड. इसे दो वर्णों वाले CLDR कोड की वैल्यू के तौर पर तय किया जाता है. कोई डिफ़ॉल्ट वैल्यू नहीं है.

  अगर जवाब में FORMATTED_ADDRESS फ़ील्ड में देश का नाम, regionCode से मेल खाता है, तो FORMATTED_ADDRESS से देश कोड हटा दिया जाता है.

  ज़्यादातर CLDR कोड, ISO 3166-1 कोड से मिलते-जुलते होते हैं. हालांकि, कुछ कोड अलग होते हैं. उदाहरण के लिए, यूनाइटेड किंगडम का सीसीटीएलडी "uk" (.co.uk) है, जबकि उसका आईएसओ 3166-1 कोड "gb" है. तकनीकी तौर पर, यह कोड "ग्रेट ब्रिटेन और उत्तरी आयरलैंड के यूनाइटेड किंगडम" की इकाई के लिए है. लागू कानून के आधार पर, इस पैरामीटर से नतीजों पर असर पड़ सकता है.

  क्षेत्र कोड पैरामीटर सेट करने के लिए, SearchNearbyRequest ऑब्जेक्ट बनाते समय setRegionCode() तरीके को कॉल करें.

अपने ऐप्लिकेशन में एट्रिब्यूशन दिखाना

जब आपका ऐप्लिकेशन, PlacesClient से मिली जानकारी दिखाता है, जैसे कि फ़ोटो और समीक्षाएं, तो ऐप्लिकेशन को ज़रूरी क्रेडिट भी दिखाना होगा.

ज़्यादा जानकारी के लिए, Places SDK for Android के लिए बनी नीतियां देखें.