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

प्लैटफ़ॉर्म चुनें: Android iOS JavaScript वेब सेवा

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

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

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

• कॉल करें PlacesClient.fetchPlace() – आईडी के हिसाब से जगह चुनने के लिए गाइड देखें.
• कॉल करें PlacesClient.findCurrentPlace() – मौजूदा जगह की जानकारी पाने के लिए गाइड देखें.
  PlacesClient.fetchPlace(), जगह की जानकारी वाले सभी डेटा फ़ील्ड के साथ काम करता है, लेकिन PlacesClient.findCurrentPlace() सिर्फ़ जगह की जानकारी के डेटा फ़ील्ड के सबसेट के साथ काम करता है. findCurrentPlace() के साथ काम न करने वाले फ़ील्ड की सूची के लिए, Android के लिए SDK टूल के फ़ील्ड से जुड़ी सहायता देखें.

किसी जगह का अनुरोध करते समय, आपको यह बताना होगा कि किस जगह का डेटा दिखाना है. ऐसा करने के लिए, 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() को कॉल करें. period ऑब्जेक्ट की सूची देने के लिए, OpeningHours.getPeriods() को कॉल करें. इस सूची में ज़्यादा जानकारी शामिल करें, जो getWeekdayText() से मिले डेटा के बराबर हो.

  ध्यान दें: अगर कोई जगह हमेशा खुली रहती है, तो समयावधि को रविवार आधी रात को दिखाया जाता है और closeEvent को शून्य के तौर पर दिखाया जाता है.

  Place ऑब्जेक्ट में getCurrentOpeningHours() तरीका भी शामिल है जो अगले सात दिनों में किसी जगह के खुले होने के समय की जानकारी देता है. साथ ही, getSecondaryOpeningHours() जो अगले सात दिनों के लिए किसी जगह के दूसरे सात दिनों के कामकाजी घंटों की जानकारी देता है.

• isOpen() – यह एक बूलियन है जिससे पता चलता है कि जगह फ़िलहाल खुली है या नहीं. अगर कोई समय तय नहीं किया गया है, तो डिफ़ॉल्ट समय को सेट किया जाता है. isOpen सिर्फ़ तब वापस किए जाएंगे, जब Place.Field.UTC_OFFSET और Place.Field.OPENING_HOURS, दोनों उपलब्ध हों. सटीक नतीजे पाने के लिए, जगह की जानकारी से जुड़े मूल अनुरोध में Place.Field.BUSINESS_STATUS और Place.Field.UTC_OFFSET फ़ील्ड का अनुरोध करें. अगर अनुरोध नहीं किया जाता है, तो यह माना जाता है कि कारोबार चालू है. जगह की जानकारी के साथ isOpen का इस्तेमाल करने का तरीका जानने के लिए, यह वीडियो देखें.

  ध्यान दें: यह तरीका अब काम नहीं करता. इसके बजाय, PlacesClient.isOpen(IsOpenRequest request) का इस्तेमाल करें. ज़्यादा जानकारी के लिए, ओपन स्टेटस पाएं देखें.

कुछ आसान उदाहरण:

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 को शुरू करने के बारे में ज़्यादा जानकारी के लिए, जगहों के एपीआई क्लाइंट को शुरू करने का तरीका देखें.

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

खुलने की स्थिति पाएं

PlacesClient.isOpen(IsOpenRequest request) तरीका, एक IsOpenResponse ऑब्जेक्ट दिखाता है. इससे पता चलता है कि कॉल में दिए गए समय के आधार पर, कारोबार फ़िलहाल खुला है या नहीं.

इस तरीके में, IsOpenRequest टाइप के एक आर्ग्युमेंट का इस्तेमाल किया जाता है, जिसमें ये चीज़ें शामिल होती हैं:

• Place ऑब्जेक्ट या जगह के आईडी को बताने वाली स्ट्रिंग.
  ध्यान दें: 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() का इस्तेमाल करता है. ज़रूरी फ़ील्ड के साथ 'जगह' ऑब्जेक्ट बनाने के बारे में ज़्यादा जानकारी के लिए, जगह की जानकारी देखें.

ध्यान दें: जगहों के बेसिक डेटा SKU का शुल्क, fetchPlace() पर किए गए कॉल के लिए Place.Field.UTC_OFFSET और Place.Field.BUSINESS_STATUS के लिए लिया जाता है. Place.Field.CURRENT_OPENING_HOURS और Place.Field.OPENING_HOURS के लिए, fetchPlace() पर किए गए कॉल के लिए, जगहें संपर्क डेटा SKU से शुल्क लिया जाता है.

यहां दिए गए उदाहरण से पता चलता है कि कोई जगह फ़िलहाल खुली है या नहीं. इस उदाहरण में, आपने सिर्फ़ जगह का आईडी 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 के लिए, 'जगहें' SDK टूल में इस्तेमाल किया गया जगह का आईडी वही है जो Location API में इस्तेमाल किया गया है. हर जगह का आईडी सिर्फ़ एक जगह से जुड़ा हो सकता है. हालांकि, एक जगह के आईडी में, एक से ज़्यादा जगह के आईडी हो सकते हैं. कुछ अन्य स्थितियों में भी, किसी जगह का नया आईडी मिल सकता है. उदाहरण के लिए, कारोबार की किसी नई जगह पर शिफ़्ट होने पर ऐसा हो सकता है.

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

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