Android के लिए जगहों का SDK टूल, आपके ऐप्लिकेशन में जगहों के बारे में ज़रूरी जानकारी देता है. इसमें जगह का नाम और पता, अक्षांश/देशांतर निर्देशांक के तौर पर बताई गई भौगोलिक जगह, जगह का टाइप (जैसे कि नाइट क्लब, पालतू जानवरों की दुकान, संग्रहालय वगैरह) शामिल है. किसी खास जगह की यह जानकारी ऐक्सेस करने के लिए, जगह का आईडी इस्तेमाल किया जा सकता है. यह एक स्थायी आइडेंटिफ़ायर होता है, जो किसी जगह की खास पहचान करता है.
जगह की जानकारी
Place
ऑब्जेक्ट, किसी खास जगह के बारे में जानकारी देता है. किसी Place
ऑब्जेक्ट को होल्ड करने के लिए, ये तरीके अपनाए जा सकते हैं:
- कॉल करें
PlacesClient.fetchPlace()
– आईडी से जगह पाने से जुड़ी गाइड देखें. - कॉल करें
PlacesClient.findCurrentPlace()
– मौजूदा जगह का पता लगाने के लिए गाइड देखें.
किसी जगह का अनुरोध करते समय, आपको यह बताना होगा कि किस जगह का डेटा दिखाना है. ऐसा करने के लिए, Place.Field की वैल्यू की सूची पास करें, जिसमें शामिल किया जाने वाला डेटा होता है. इस सूची पर विचार करना ज़रूरी है, क्योंकि इससे हर अनुरोध की लागत पर असर पड़ता है.
जगह से जुड़े डेटा के नतीजे खाली नहीं हो सकते. इसलिए, सिर्फ़ डेटा वाले नतीजे दिखाए जाते हैं. उदाहरण के लिए, अगर किसी जगह के लिए अनुरोध की गई जगह पर कोई फ़ोटो मौजूद नहीं है, तो नतीजे में photos
फ़ील्ड नहीं दिखेगा.
नीचे दिया गया उदाहरण, अनुरोध से मिला डेटा तय करने के लिए तीन Place.Field वैल्यू की सूची पास करता है:
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Java
// Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
जगह की जानकारी के डेटा के फ़ील्ड ऐक्सेस करें
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.name val address = place.address val location = place.latLng
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
आईडी के हिसाब से जगह की जानकारी पाएं
जगह का आईडी, टेक्स्ट के तौर पर एक आइडेंटिफ़ायर होता है. यह किसी जगह की खास तौर पर पहचान करता है. Android के लिए, Places SDK टूल में,
Place.getId()
को कॉल करके किसी जगह का आईडी वापस पाया जा सकता है.
जगह की जानकारी अपने-आप भर जाने की सुविधा
सेवा, हर उस जगह के लिए जगह का आईडी भी दिखाती है जो दी गई खोज क्वेरी
और फ़िल्टर से मेल खाती है. आपके पास जगह का आईडी सेव करने और उसका इस्तेमाल करके,
Place
ऑब्जेक्ट को बाद में फिर से पाने का विकल्प है.
आईडी के ज़रिए कोई जगह पाने के लिए, PlacesClient.fetchPlace()
को कॉल करें और FetchPlaceRequest
पास करें.
एपीआई,
Task
में
FetchPlaceResponse
दिखाता है.
FetchPlaceResponse
में
Place
ऑब्जेक्ट, दिए गए जगह के आईडी से मेल खाता है.
नीचे दिए गए कोड के उदाहरण में, किसी खास जगह की जानकारी पाने के लिए fetchPlace()
पर कॉल करने के बारे में बताया गया है.
Kotlin
// Define a Place ID. val placeId = "INSERT_PLACE_ID_HERE" // Specify the fields to return. val placeFields = listOf(Place.Field.ID, Place.Field.NAME) // 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 Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}") }.addOnFailureListener { exception: Exception -> if (exception is ApiException) { 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 = "INSERT_PLACE_ID_HERE"; // Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // 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(); Log.i(TAG, "Place found: " + place.getName()); }).addOnFailureListener((exception) -> { if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; 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_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
अगर Place
ऑब्जेक्ट में ये फ़ील्ड नहीं दिए गए हैं या जगह का आईडी पास किया जाता है, तो उन्हें फ़ेच करने के लिए यह तरीका PlacesClient.fetchPlace()
का इस्तेमाल करता है. ज़रूरी फ़ील्ड के साथ 'जगह की जानकारी' बनाने के बारे में ज़्यादा जानकारी के लिए, जगह की जानकारी देखें.
इस उदाहरण से पता चलता है कि कोई जगह अभी खुली है या नहीं. इस उदाहरण में, आप सिर्फ़ isOpen()
को जगह का आईडी पास करते हैं:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response -> val isOpen = response.isOpen } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) -> isOpen = response.isOpen()); // ...
अगले उदाहरण में, isOpen()
को कॉल करने के बारे में बताया गया है, जहां Place
ऑब्जेक्ट पास किया जाता है.
Place
ऑब्जेक्ट में, मान्य जगह का आईडी होना चाहिए:
Kotlin
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk" // 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.UTC_OFFSET ) 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) { e.printStackTrace() return@addOnSuccessListener } val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse -> val isOpen = isOpenResponse.isOpen } // ... } // ...
Java
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"; // 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.UTC_OFFSET )); 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) { e.printStackTrace(); return; } Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) -> isOpen = isOpenResponse.isOpen()); // ... }); // ...
अपने ऐप्लिकेशन में एट्रिब्यूशन दिखाएं
जब आपका ऐप्लिकेशन, जगह की जानकारी के साथ-साथ जगह की जानकारी भी दिखाता है, तो ऐप्लिकेशन को एट्रिब्यूशन भी दिखाना चाहिए. ज़्यादा जानकारी के लिए, एट्रिब्यूशन देखें.
जगह के आईडी के बारे में ज़्यादा जानकारी
Android के लिए Places SDK में इस्तेमाल किया गया जगह का आईडी, वही आइडेंटिफ़ायर होता है जिसका इस्तेमाल जगहें एपीआई में किया जाता है. हर जगह का आईडी सिर्फ़ एक जगह के बारे में बता सकता है, लेकिन किसी एक जगह के एक से ज़्यादा आईडी हो सकते हैं. कुछ दूसरी वजहों से भी, जगह को नया जगह का आईडी मिल सकता है. उदाहरण के लिए, ऐसा तब हो सकता है, जब कोई कारोबार किसी नई जगह पर शिफ़्ट हो जाता है.
किसी जगह का आईडी देकर किसी जगह का अनुरोध करने पर, आपको इस बात पर भरोसा हो सकता है कि जवाब में आपको हमेशा एक ही जगह मिलेगी (अगर जगह अब भी मौजूद है). हालांकि, ध्यान दें कि जवाब में ऐसी जगह का आईडी हो सकता है जो आपके अनुरोध में दिए गए आईडी से अलग हो.
ज़्यादा जानकारी के लिए, जगह के आईडी की खास जानकारी देखें.