जगह की जानकारी

Android के लिए Places SDK, आपके ऐप्लिकेशन को जगहों के बारे में ज़्यादा जानकारी देता है. इसमें जगह का नाम और पता, अक्षांश/देशांतर के निर्देशांक के तौर पर बताई गई भौगोलिक जगह, जगह का टाइप (जैसे, नाइट क्लब, पालतू जानवरों का स्टोर, संग्रहालय) वगैरह शामिल है. किसी खास जगह के लिए यह जानकारी ऐक्सेस करने के लिए, जगह का आईडी इस्तेमाल किया जा सकता है. यह एक ऐसा आइडेंटिफ़ायर है जो किसी जगह की यूनीक पहचान करता है.

जगह की जानकारी

Place ऑब्जेक्ट, किसी खास जगह के बारे में जानकारी देता है. Place ऑब्जेक्ट को इन तरीकों से ऐक्सेस किया जा सकता है:

• कॉल करें PlacesClient.fetchPlace() – जगह का आईडी डालकर उसे खोजने का तरीका जानने के लिए गाइड देखें.
• कॉल करें PlacesClient.findCurrentPlace() – मौजूदा जगह की जानकारी पाने के लिए गाइड देखें.

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

जगह का डेटा खाली नहीं हो सकता, इसलिए सिर्फ़ जगह के ऐसे नतीजे दिखाए जाते हैं जिनमें डेटा हो. उदाहरण के लिए, अगर अनुरोध की गई जगह की कोई फ़ोटो नहीं है, तो नतीजे में photos फ़ील्ड मौजूद नहीं होगा.

इस उदाहरण में, अनुरोध से मिले डेटा की जानकारी देने के लिए, तीन Place.Field वैल्यू की सूची दी गई है:

// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
  

जगह के ऑब्जेक्ट के डेटा फ़ील्ड ऐक्सेस करना

Place ऑब्जेक्ट पाने के बाद, अनुरोध में बताए गए डेटा फ़ील्ड को ऐक्सेस करने के लिए, ऑब्जेक्ट के तरीकों का इस्तेमाल करें. अगर Place ऑब्जेक्ट में फ़ील्ड मौजूद नहीं है, तो उससे जुड़ा तरीका null दिखाता है. यहां उपलब्ध कुछ तरीकों के उदाहरण दिए गए हैं.

• 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 का इस्तेमाल करने का तरीका जानने के लिए, यह वीडियो देखें.

कुछ उदाहरण:

val name = place.name
val address = place.address
val location = place.latLng

      

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

आईडी के हिसाब से जगह की जानकारी पाना

प्लेस आईडी, टेक्स्ट वाला एक आइडेंटिफ़ायर होता है. इससे किसी जगह की खास पहचान की जाती है. Android के लिए Places SDK टूल में, Place.getId() को कॉल करके किसी जगह का आईडी पाया जा सकता है. जगह की जानकारी अपने-आप पूरी होने की सुविधा वाली सेवा, खोज क्वेरी और फ़िल्टर से मैच होने वाली हर जगह के लिए, एक जगह का आईडी भी दिखाती है. प्लेस आईडी को सेव किया जा सकता है और इसका इस्तेमाल, बाद में Place ऑब्जेक्ट को फिर से पाने के लिए किया जा सकता है.

आईडी के हिसाब से कोई जगह पाने के लिए, FetchPlaceRequest को पास करते हुए, PlacesClient.fetchPlace() को कॉल करें.

एपीआई, Task में एक FetchPlaceResponse दिखाता है. FetchPlaceResponse में, दिए गए प्लेस आईडी से मैच करने वाला Place ऑब्जेक्ट होता है.

यहां दिए गए कोड के उदाहरण में, किसी जगह की जानकारी पाने के लिए fetchPlace() को कॉल करने का तरीका बताया गया है.

// 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")
        }
    }

      

// 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() को जगह का आईडी पास किया जाता है:

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
}
// ...

      

@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 ऑब्जेक्ट में एक मान्य प्लेस आईडी होना चाहिए:

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
    }
    // ...
}
// ...

      

@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());
            // ...
        });
// ...

      

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

जब आपका ऐप्लिकेशन किसी जगह की जानकारी दिखाता है, तो उसमें जगह की समीक्षाओं के साथ-साथ, ऐट्रिब्यूशन भी दिखाए जाने चाहिए. ज़्यादा जानकारी के लिए, एट्रिब्यूशन देखें.

प्लेस आईडी के बारे में ज़्यादा जानकारी

Places SDK for Android में इस्तेमाल किया जाने वाला जगह का आईडी, Places API में इस्तेमाल किए गए आइडेंटिफ़ायर जैसा ही होता है. हर प्लेस आईडी, सिर्फ़ एक जगह के बारे में बता सकता है. हालांकि, किसी एक जगह के लिए एक से ज़्यादा प्लेस आईडी हो सकते हैं. ऐसी अन्य स्थितियां भी हो सकती हैं जिनकी वजह से किसी जगह को नया प्लेस आईडी मिल सकता है. उदाहरण के लिए, ऐसा तब हो सकता है, जब कोई कारोबार किसी नई जगह पर शिफ़्ट हो जाए.

किसी जगह का आईडी डालकर अनुरोध करने पर, आपको भरोसा रहेगा कि आपको जवाब में हमेशा वही जगह दिखेगी (अगर वह जगह अब भी मौजूद है). हालांकि, ध्यान दें कि जवाब में ऐसा प्लेस आईडी हो सकता है जो आपके अनुरोध में दिए गए प्लेस आईडी से अलग हो.

ज़्यादा जानकारी के लिए, जगह के आईडी की खास जानकारी देखें.