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

यूरोपियन इकनॉमिक एरिया (ईईए) के डेवलपर

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 ऑब्जेक्ट में फ़ील्ड मौजूद नहीं है, तो इससे जुड़ा तरीका शून्य दिखाता है. नीचे, उपलब्ध कुछ तरीकों के उदाहरण दिए गए हैं.

  • 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_STATUS
  • Place.Field.CURRENT_OPENING_HOURS
  • Place.Field.OPENING_HOURS
  • Place.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 में इस्तेमाल किए गए आइडेंटिफ़ायर के जैसा ही होता है. हर प्लेस आईडी, सिर्फ़ एक जगह से जुड़ा हो सकता है. हालांकि, एक जगह के लिए एक से ज़्यादा प्लेस आईडी हो सकते हैं. ऐसी अन्य स्थितियां भी हो सकती हैं जिनकी वजह से किसी जगह को नया प्लेस आईडी मिल सकता है. उदाहरण के लिए, ऐसा तब हो सकता है, जब कोई कारोबार नई जगह पर शिफ़्ट हो जाता है.

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

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