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