Places SDK for Android (लेगसी) आपके ऐप्लिकेशन को जगहों के बारे में ज़्यादा जानकारी देता है. इसमें जगह का नाम और पता, अक्षांश/देशांतर निर्देशांक के तौर पर बताई गई भौगोलिक जगह, जगह का टाइप (जैसे, नाइट क्लब, पेट स्टोर, म्यूज़ियम) वगैरह शामिल है. किसी खास जगह की जानकारी ऐक्सेस करने के लिए, जगह के आईडी का इस्तेमाल किया जा सकता है. यह एक ऐसा आइडेंटिफ़ायर है जो किसी जगह की खास तौर पर पहचान करता है.
जगह की जानकारी
Place ऑब्जेक्ट, किसी खास जगह के बारे में जानकारी देता है. PlacesClient.fetchPlace() को कॉल करके, Place ऑब्जेक्ट को ऐक्सेस किया जा सकता है – आईडी से किसी जगह की जानकारी पाने की गाइड देखें.
किसी जगह की जानकारी का अनुरोध करते समय, आपको यह बताना होगा कि आपको उस जगह का कौनसा डेटा चाहिए. इसके लिए, Place.Field वैल्यू की एक सूची पास करें. इसमें वह डेटा शामिल होना चाहिए जो आपको चाहिए. यह सूची एक अहम जानकारी है, क्योंकि इससे हर अनुरोध की लागत पर असर पड़ता है.
जगह की जानकारी के डेटा के नतीजे खाली नहीं हो सकते. इसलिए, सिर्फ़ डेटा वाले नतीजे दिखाए जाते हैं. उदाहरण के लिए, अगर अनुरोध की गई जगह की कोई फ़ोटो नहीं है, तो नतीजे में photos फ़ील्ड मौजूद नहीं होगा.
यहां दिए गए उदाहरण में, अनुरोध से मिले डेटा की जानकारी देने के लिए, तीन Place.Field वैल्यू की सूची पास की गई है:
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)
Java
// Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);
Place ऑब्जेक्ट के डेटा फ़ील्ड ऐक्सेस करना
Place ऑब्जेक्ट मिलने के बाद, अनुरोध में बताए गए डेटा फ़ील्ड को ऐक्सेस करने के लिए, ऑब्जेक्ट के तरीकों का इस्तेमाल करें. अगर Place ऑब्जेक्ट में फ़ील्ड मौजूद नहीं है, तो उससे जुड़ा तरीका शून्य दिखाता है. यहां कुछ उपलब्ध तरीकों के उदाहरण दिए गए हैं.
getAddress()– जगह का पता, जिसे आसानी से पढ़ा जा सके.getAddressComponents()– इस जगह के पते के कॉम्पोनेंट कीList. इन कॉम्पोनेंट का इस्तेमाल, किसी जगह के पते के बारे में स्ट्रक्चर्ड जानकारी निकालने के लिए किया जाता है. उदाहरण के लिए, यह पता लगाना कि कोई जगह किस शहर में है. पते को फ़ॉर्मैट करने के लिए, इन कॉम्पोनेंट का इस्तेमाल न करें. इसके बजाय,getAddress()को कॉल करें. इससे आपको स्थानीय भाषा में फ़ॉर्मैट किया गया पता मिलेगा.getId()– जगह के लिए टेक्स्ट आइडेंटिफ़ायर. इस पेज पर, जगह के आईडी के बारे में ज़्यादा जानें.getLatLng()– जगह की भौगोलिक जानकारी, जिसे अक्षांश और देशांतर निर्देशांक के तौर पर बताया गया है.getName()– जगह का नाम.getOpeningHours()– जगह काOpeningHours.OpeningHours.getWeekdayText()को कॉल करें, ताकि स्ट्रिंग की ऐसी सूची मिले जो हफ़्ते के हर दिन के लिए, कारोबार के खुलने और बंद होने का समय दिखाती हो.OpeningHours.getPeriods()को कॉल करके,periodऑब्जेक्ट की ऐसी सूची पाना जिसमें ज़्यादा जानकारी हो. यह जानकारी,getWeekdayText()से मिले डेटा के बराबर होती है.Placeऑब्जेक्ट में,getCurrentOpeningHours()मेथड भी शामिल होता है. इससे, अगले सात दिनों के दौरान किसी जगह के खुले होने के समय की जानकारी मिलती है. साथ ही,getSecondaryOpeningHours()मेथड से, अगले सात दिनों के दौरान किसी जगह के खुले होने के सेकंडरी समय की जानकारी मिलती है.isOpen()– बूलियन वैल्यू, जिससे पता चलता है कि जगह फ़िलहाल खुली है या नहीं. अगर कोई समय तय नहीं किया गया है, तो डिफ़ॉल्ट रूप से 'अभी' को चुना जाता है.isOpenसिर्फ़ तब दिखाया जाएगा, जबPlace.Field.UTC_OFFSETऔरPlace.Field.OPENING_HOURS, दोनों उपलब्ध हों. सटीक नतीजे पाने के लिए, जगह की जानकारी के अपने ओरिजनल अनुरोध मेंPlace.Field.BUSINESS_STATUSऔरPlace.Field.UTC_OFFSETफ़ील्ड का अनुरोध करें. अगर अनुरोध नहीं किया जाता है, तो यह माना जाता है कि कारोबार चालू है. जगह की जानकारी के साथisOpenका इस्तेमाल करने का तरीका जानने के लिए, यह वीडियो देखें.
कुछ उदाहरण:
Kotlin
val name = place.displayName val address = place.formattedAddress val location = place.location
Java
final CharSequence name = place.getDisplayName(); final CharSequence address = place.getFormattedAddress(); final LatLng location = place.getLocation();
आईडी के हिसाब से जगह की जानकारी फ़ेच करें
जगह का आईडी, टेक्स्ट के तौर पर मौजूद एक आइडेंटिफ़ायर होता है. इससे किसी जगह की खास तौर पर पहचान की जाती है. Places SDK for Android में, Place.getId() को कॉल करके किसी जगह का आईडी वापस पाया जा सकता है.
किसी जगह के शुरुआती अक्षर लिखने पर पूरा नाम सुझाने की सुविधा सेवा, दी गई सर्च क्वेरी और फ़िल्टर से मैच होने वाली हर जगह के लिए, जगह का आईडी भी दिखाती है. जगह के आईडी को सेव किया जा सकता है. साथ ही, बाद में
Place
ऑब्जेक्ट को फिर से पाने के लिए, इसका इस्तेमाल किया जा सकता है.
आईडी से किसी जगह की जानकारी पाने के लिए, PlacesClient.fetchPlace() को कॉल करें और FetchPlaceRequest पास करें.
एपीआई,
Task
में
FetchPlaceResponse
दिखाता है.
FetchPlaceResponse में एक Place ऑब्जेक्ट होता है, जो दिए गए जगह के आईडी से मैच करता है.
यहां दिए गए कोड के उदाहरण में, किसी जगह की जानकारी पाने के लिए fetchPlace() को कॉल करने का तरीका बताया गया है.
Kotlin
// Define a Place ID. val placeId = PlaceIdProvider.getRandomPlaceId() // Specify the fields to return. val placeFields = listOf( Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION, ) // Construct a request object, passing the place ID and fields array. val request = FetchPlaceRequest.newInstance(placeId, placeFields) placesClient.fetchPlace(request) .addOnSuccessListener { response: FetchPlaceResponse -> val place = response.place val name = place.displayName val address = place.formattedAddress val location = place.location binding.placeName.text = name binding.placeAddress.text = address if (location != null) { binding.placeLocation.text = getString( R.string.place_location, location.latitude, location.longitude, ) } else { binding.placeLocation.text = null } Log.i(TAG, "Place found: ${place.displayName}") }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { val message = getString(R.string.place_not_found, exception.message) binding.placeName.text = message Log.e(TAG, "Place not found: ${exception.message}") val statusCode = exception.statusCode TODO("Handle error with given status code") } }
Java
// Define a Place ID. final String placeId = PlaceIdProvider.getRandomPlaceId(); // Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList( Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION); // Construct a request object, passing the place ID and fields array. final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); placesClient .fetchPlace(request) .addOnSuccessListener( (response) -> { Place place = response.getPlace(); final CharSequence name = place.getDisplayName(); final CharSequence address = place.getFormattedAddress(); final LatLng location = place.getLocation(); binding.placeName.setText(name); binding.placeAddress.setText(address); if (location != null) { binding.placeLocation.setText( getString( R.string.place_location, location.latitude, location.longitude)); } else { binding.placeLocation.setText(null); } Log.i(TAG, "Place found: " + place.getDisplayName()); }) .addOnFailureListener( (exception) -> { if (exception instanceof ApiException apiException) { final String message = getString( R.string.place_not_found, apiException.getMessage()); binding.placeName.setText(message); Log.e(TAG, "Place not found: " + exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } });
अटैचमेंट खोले जाने का स्टेटस देखना
PlacesClient.isOpen(IsOpenRequest request) तरीका, IsOpenResponse ऑब्जेक्ट दिखाता है. इससे पता चलता है कि कॉल में बताए गए समय के हिसाब से, जगह फ़िलहाल खुली है या नहीं.
यह तरीका, IsOpenRequest टाइप का एक आर्ग्युमेंट लेता है. इसमें ये शामिल होते हैं:
- कोई
Placeऑब्जेक्ट या जगह का आईडी बताने वाली स्ट्रिंग. - यह समय की वैल्यू होती है, जिसे मिलीसेकंड में बताया जाता है. यह वैल्यू 1970-01-01T00:00:00Z से शुरू होती है. इसे तय करना ज़रूरी नहीं है. अगर कोई समय तय नहीं किया गया है, तो डिफ़ॉल्ट रूप से 'अभी' को चुना जाता है.
इस तरीके के लिए, Place ऑब्जेक्ट में ये फ़ील्ड मौजूद होने चाहिए:
Place.Field.BUSINESS_STATUSPlace.Field.CURRENT_OPENING_HOURSPlace.Field.OPENING_HOURSPlace.Field.UTC_OFFSET
अगर ये फ़ील्ड Place ऑब्जेक्ट में नहीं दिए गए हैं या आपने जगह का आईडी पास किया है, तो उन्हें फ़ेच करने के लिए, यह तरीका PlacesClient.fetchPlace() का इस्तेमाल करता है. ज़रूरी फ़ील्ड के साथ Place ऑब्जेक्ट बनाने के बारे में ज़्यादा जानने के लिए, जगह की जानकारी देखें.
इस उदाहरण से पता चलता है कि कोई जगह फ़िलहाल खुली है या नहीं. इस उदाहरण में, जगह का आईडी सिर्फ़ isOpen() को पास किया जाता है:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = PlaceIdProvider.getRandomPlaceId() val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { Log.e("PlaceIsOpen", "Error: " + e.message) return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen ?: false binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString()) Log.d("PlaceIsOpen", "Is open by ID: $isOpen") } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = PlaceIdProvider.getRandomPlaceId(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { Log.e("PlaceIsOpen", "Error: " + e.getMessage()); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> { final boolean isOpen = Boolean.TRUE.equals(response.isOpen()); binding.isOpenByIdResult.setText( getString(R.string.is_open_by_id, String.valueOf(isOpen))); Log.d("PlaceIsOpen", "Is open by ID: " + isOpen); }); placeTask.addOnFailureListener( (exception) -> { binding.isOpenByIdResult.setText( getString(R.string.is_open_by_id, "Error: " + exception.getMessage())); Log.e("PlaceIsOpen", "Error: " + exception.getMessage()); });
इस उदाहरण में, isOpen() को कॉल करने का तरीका बताया गया है. इसमें Place ऑब्जेक्ट को पास किया जाता है.
Place ऑब्जेक्ट में जगह का मान्य आईडी होना चाहिए:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = PlaceIdProvider.getRandomPlaceId() // Specify the required fields for an isOpen request. val placeFields: List<Place.Field> = listOf( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.DISPLAY_NAME, ) val placeRequest: FetchPlaceRequest = FetchPlaceRequest.newInstance(placeId, placeFields) val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest) placeTask.addOnSuccessListener { placeResponse -> place = placeResponse.place val isOpenRequest: IsOpenRequest = try { IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { Log.e("PlaceIsOpen", "Error: " + e.message) return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = when (isOpenResponse.isOpen) { true -> getString(R.string.is_open) else -> getString(R.string.is_closed) } binding.isOpenByObjectResult.text = getString( R.string.is_open_by_object, place.displayName, isOpen, ) Log.d("PlaceIsOpen", "Is open by object: $isOpen") } // ... } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = PlaceIdProvider.getRandomPlaceId(); // Specify the required fields for an isOpen request. List<Place.Field> placeFields = new ArrayList<>( Arrays.asList( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.DISPLAY_NAME)); FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request); placeTask.addOnSuccessListener( (placeResponse) -> { Place place = placeResponse.getPlace(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { Log.e("PlaceIsOpen", "Error: " + e.getMessage()); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> { final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen()); binding.isOpenByObjectResult.setText( getString( R.string.is_open_by_object, place.getDisplayName(), String.valueOf(isOpen))); Log.d("PlaceIsOpen", "Is open by object: " + isOpen); }); isOpenTask.addOnFailureListener( (exception) -> { // also update the result text field binding.isOpenByObjectResult.setText( getString( R.string.is_open_by_object, place.getDisplayName(), "Error: " + exception.getMessage())); Log.e("PlaceIsOpen", "Error: " + exception.getMessage()); }); }); placeTask.addOnFailureListener( (exception) -> { binding.isOpenByObjectResult.setText("Error: " + exception.getMessage()); Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
अपने ऐप्लिकेशन में एट्रिब्यूशन दिखाना
जब आपका ऐप्लिकेशन किसी जगह की जानकारी दिखाता है, जिसमें जगह की समीक्षाएं भी शामिल हैं, तो ऐप्लिकेशन को कोई भी एट्रिब्यूशन भी दिखाना चाहिए. ज़्यादा जानकारी के लिए, एट्रिब्यूशन देखें.
जगह के आईडी के बारे में ज़्यादा जानकारी
Places SDK for Android (लेगसी) में इस्तेमाल किया गया जगह का आईडी, वही आइडेंटिफ़ायर है जो Places API (लेगसी) में इस्तेमाल किया गया है. हर जगह का आईडी सिर्फ़ एक जगह के लिए हो सकता है. हालांकि, एक जगह के लिए एक से ज़्यादा आईडी हो सकते हैं. ऐसी अन्य स्थितियां भी हो सकती हैं जिनकी वजह से किसी जगह को नया जगह का आईडी मिल सकता है. उदाहरण के लिए, ऐसा तब हो सकता है, जब कोई कारोबार किसी नई जगह पर शिफ़्ट हो जाए.
किसी जगह का आईडी डालकर, उस जगह की जानकारी का अनुरोध करने पर, आपको हमेशा जवाब में उसी जगह की जानकारी मिलेगी. हालांकि, ऐसा तब होगा, जब वह जगह अब भी मौजूद हो. हालांकि, ध्यान दें कि जवाब में ऐसा जगह का आईडी हो सकता है जो आपके अनुरोध में दिए गए जगह का आईडी से अलग हो.
ज़्यादा जानकारी के लिए, जगह के आईडी की खास जानकारी देखें.