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 ListplaceFields = 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();
वर्शन 3.3.0 में जोड़े गए जगह का डेटा ऐक्सेस करें
Android के 3.3.0 वर्शन के लिए, Places SDK टूल
Place
में नया डेटा जोड़ता है:
- जगह के टाइप: किसी जगह से जुड़ी नई टाइप की वैल्यू.
- समीक्षाएं: किसी जगह के लिए, ज़्यादा से ज़्यादा पांच समीक्षाएं.
- नाम का भाषा कोड: किसी जगह के नाम के लिए भाषा कोड.
नीचे दिए सेक्शन में, इस नए डेटा को ऐक्सेस करने का तरीका बताया गया है.
नई तरह की जगहों को ऐक्सेस करें
हर जगह के साथ एक या एक से ज़्यादा टाइप वैल्यू हो सकती हैं. Android के लिए Places SDK टूल के वर्शन 3.3.0 में कई नई तरह की वैल्यू जोड़ी गई हैं. पूरी सूची के लिए, बड़ी जगहों के टाइप देखें.
Android के लिए, Places SDK टूल में 3.2.0 और इससे पहले के वर्शन में, किसी जगह से जुड़ी टाइप वैल्यू को ऐक्सेस करने के लिए, आपने Place.getTypes()
तरीके का इस्तेमाल किया था. Place.getTypes()
, Place.Types
से तय की गई enum वैल्यू के तौर पर टाइप की सूची दिखाता है.
Place.getPlaceTypes()
तरीका, टाइप वैल्यू को स्ट्रिंग वैल्यू की सूची के तौर पर दिखाता है. दिखाए जाने वाले मान, Android के लिए स्थल SDK टूल के आपके वर्शन
पर निर्भर करते हैं:
- Android के लिए SDK टूल (नया): यह फ़ंक्शन, जगह के टाइप (नया) में टेबल A और टेबल B से तय की गई स्ट्रिंग दिखाता है. इसमें, वर्शन 3.3.0 में जोड़ी गई जगह के सभी टाइप भी शामिल होते हैं.
- Android के लिए SDK टूल की जगह: यह फ़ंक्शन,
Place.Types
के तय किए गए Enum की वैल्यू दिखाता है, जिनमें वर्शन 3.3.0 में जोड़े गए नए टाइप शामिल नहीं होते.
SDK टूल के दोनों वर्शन के बीच के मुख्य अंतर के बारे में जानने के लिए, SDK टूल का वर्शन चुनना लेख पढ़ें.
जगह की समीक्षाएं ऐक्सेस करें
Android के लिए जगहें SDK टूल (नया) Review
क्लास जोड़ता है, जिसमें किसी जगह की समीक्षा होती है. Place
ऑब्जेक्ट में ज़्यादा से ज़्यादा पांच समीक्षाएं हो सकती हैं.
Review
क्लास में, कोई एट्रिब्यूशन और लेखक का एट्रिब्यूशन भी शामिल हो सकता है. अगर आप
अपने ऐप्लिकेशन में समीक्षा दिखाते हैं, तो आपको कोई भी एट्रिब्यूशन या लेखक का एट्रिब्यूशन भी दिखाना होगा.
ज़्यादा जानकारी के लिए, समीक्षा दिखाना लेख पढ़ें.
Place
ऑब्जेक्ट को समीक्षाओं से भरने के लिए, आपको:
- अपना Google Cloud प्रोजेक्ट सेट अप करते समय, नए SDK टूल को चालू करें.
- किसी गतिविधि या फ़्रैगमेंट में नए SDK टूल को शुरू करें.
- जगह की जानकारी के अनुरोध की फ़ील्ड सूची में
Place.Field.REVIEWS
को शामिल करें. PlacesClient.fetchPlace()
पर कॉल करें. समीक्षा फ़ील्ड,PlacesClient.findCurrentPlace()
पर काम नहीं करता.Place
ऑब्जेक्ट में, समीक्षाओं के डेटा फ़ील्ड को ऐक्सेस करने के लिए,Place.getReviews()
तरीके का इस्तेमाल करें.
जगह के नाम का भाषा कोड ऐक्सेस करें
मौजूदा Place.getName()
तरीका, ऐसी टेक्स्ट स्ट्रिंग दिखाता है जिसमें जगह का नाम होता है. Place
ऑब्जेक्ट को जगह के नाम से भरने के लिए, आपको जगह की जानकारी के अनुरोध की फ़ील्ड सूची में Place.Field.NAME
शामिल करना होगा.
Place
ऑब्जेक्ट में अब नाम वाली स्ट्रिंग का भाषा कोड शामिल है. Place
ऑब्जेक्ट को भाषा कोड से भरने के लिए, आपको ये काम करने होंगे:
- अपना Google Cloud प्रोजेक्ट सेट अप करते समय, नए SDK टूल को चालू करें.
- किसी गतिविधि या फ़्रैगमेंट में नए SDK टूल को शुरू करें.
- अनुरोध की फ़ील्ड सूची में
Place.Field.NAME
शामिल करें. यह वैल्यू, रिस्पॉन्स को कॉन्फ़िगर करती है, ताकिPlace
ऑब्जेक्ट में जगह का नाम और भाषा कोड, दोनों शामिल किए जा सकें. PlacesClient.fetchPlace()
पर कॉल करें.PlacesClient.findCurrentPlace()
में भाषा कोड फ़ील्ड के साथ काम नहीं करता.Place
ऑब्जेक्ट में, भाषा कोड फ़ील्ड को ऐक्सेस करने के लिए,Place.getNameLanguageCode()
तरीके का इस्तेमाल करें.
वर्शन 3.3.0 में क्षेत्रीय कोड सेट करें
Android के लिए Places SDK टूल (नया) जगह की जानकारी में, इलाके के कोड के अनुरोध का पैरामीटर जोड़ता है. इलाके के कोड का इस्तेमाल, रिस्पॉन्स को फ़ॉर्मैट करने के लिए किया जाता है. इसे दो वर्ण वाले CLDR कोड की वैल्यू के तौर पर बताया जाता है. इस पैरामीटर से खोज के नतीजों पर असर पड़ सकता है. कोई डिफ़ॉल्ट वैल्यू नहीं है. इलाके का कोड सेट करने के लिए, आपको नए SDK टूल को चालू करना होगा.
अगर जवाब में पते के फ़ील्ड में दिए गए देश का नाम, क्षेत्र के कोड से मेल खाता है, तो पते से देश कोड हटा दिया जाता है.
ज़्यादातर CLDR कोड, ISO 3166-1 कोड के जैसे ही होते हैं. हालांकि, इसमें कुछ अपवाद भी हैं. उदाहरण के लिए, यूनाइटेड किंगडम का ccTLD "uk" (.co.uk) है, जबकि इसका ISO 3166-1 कोड "gb" है (तकनीकी रूप से "यूनाइटेड किंगडम ऑफ़ ग्रेट ब्रिटेन और नॉदर्न आयरलैंड" की इकाई के लिए). पैरामीटर, लागू कानून के आधार पर नतीजों पर असर डाल सकता है.
आईडी के हिसाब से जगह की जानकारी पाएं
जगह का आईडी, टेक्स्ट के रूप में एक आइडेंटिफ़ायर होता है. यह किसी जगह की खास तौर पर पहचान करता है. Android के लिए जगहें 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 में इस्तेमाल किया गया जगह का आईडी, वही आइडेंटिफ़ायर होता है जिसका इस्तेमाल Locations API में किया गया है. हर जगह के आईडी में सिर्फ़ एक जगह का आईडी हो सकता है. हालांकि, एक जगह के लिए एक से ज़्यादा आईडी हो सकते हैं. कुछ दूसरी स्थितियों की वजह से भी किसी जगह को नया जगह का आईडी मिल सकता है. उदाहरण के लिए, ऐसा तब हो सकता है, जब कोई कारोबार किसी नई जगह पर शिफ़्ट हो जाए.
जब आप किसी जगह का आईडी देकर किसी जगह का अनुरोध करते हैं, तो आपको इस बात पर भरोसा हो सकता है कि आपको जवाब में हमेशा वही जगह मिलेगी (अगर वह जगह अब भी मौजूद है). हालांकि, ध्यान दें कि जवाब में जगह का ऐसा आईडी हो सकता है जो आपके अनुरोध में दिए गए जगह का आईडी से अलग हो.
ज़्यादा जानकारी के लिए, जगह के आईडी की खास जानकारी वाला लेख पढ़ें.