भौगोलिक स्थान से जुड़ा अनुरोध और जवाब

जियोलोकेशन के अनुरोध

जियोलोकेशन के अनुरोध, POST का इस्तेमाल करके इस यूआरएल पर भेजे जाते हैं:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

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

अनुरोध का मुख्य भाग

अनुरोध का मुख्य हिस्सा, JSON फ़ॉर्मैट में होना चाहिए. अगर अनुरोध के मुख्य हिस्से को शामिल नहीं किया जाता है, तो नतीजे, अनुरोध की जगह के आईपी पते के आधार पर दिखाए जाते हैं. यहां दिए गए फ़ील्ड इस्तेमाल किए जा सकते हैं. हालांकि, इनमें से किसी भी फ़ील्ड में जानकारी देना ज़रूरी नहीं है. अगर किसी फ़ील्ड में जानकारी देना ज़रूरी है, तो उसके बारे में साफ़ तौर पर बताया जाएगा:

Geolocation API के अनुरोध के मुख्य हिस्से का उदाहरण यहां दिया गया है.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

सेल टॉवर ऑब्जेक्ट

अनुरोध के मुख्य भाग के cellTowers कलेक्शन में, शून्य या उससे ज़्यादा सेल टावर ऑब्जेक्ट होते हैं.

यहां दिए गए ज़रूरी नहीं वाले फ़ील्ड का इस्तेमाल नहीं किया जाता. हालांकि, अगर वैल्यू उपलब्ध हैं, तो इन्हें शामिल किया जा सकता है.

cellId का हिसाब लगाया जा रहा है

NR (5G) से पहले के रेडियो टाइप, नेटवर्क सेल आईडी को Geolocation API पर भेजने के लिए, 32-बिट cellId फ़ील्ड का इस्तेमाल करते हैं.

• GSM (2G) नेटवर्क, 16-बिट वाले सेल आईडी (सीआईडी) का इस्तेमाल करते हैं. मान्य रेंज: 0–65535.
• CDMA (2G) नेटवर्क, 16-बिट वाले बेस स्टेशन आईडी (बीआईडी) का इस्तेमाल करते हैं. मान्य सीमा: 0–65535.
• WCDMA (3G) नेटवर्क, UTRAN/GERAN सेल आइडेंटिटी (UC-ID) का इस्तेमाल करते हैं. यह 28-बिट पूर्णांक होता है. इसमें 12-बिट रेडियो नेटवर्क कंट्रोलर आइडेंटिफ़ायर (RNC-ID) और 16-बिट सेल आईडी (CID) शामिल होते हैं.
  फ़ॉर्मूला: rnc_id << 16 | cid.
  मान्य सीमा: 0–26,84,35,455.
  ध्यान दें: WCDMA नेटवर्क में सिर्फ़ 16-बिट सेल आईडी वैल्यू डालने पर, नतीजे गलत मिलते हैं या कोई नतीजा नहीं मिलता.
• एलटीई (4G) नेटवर्क, E-UTRAN Cell Identity (ECI) का इस्तेमाल करते हैं. यह 28-बिट पूर्णांक वैल्यू होती है. इसमें 20-बिट E-UTRAN Node B Identifier (eNBId) और 8-बिट Cell ID (CID) शामिल होते हैं.
  फ़ॉर्मूला: enb_id << 8 | cid.
  मान्य सीमा: 0–26,84,35,455.
  ध्यान दें: एलटीई नेटवर्क में सिर्फ़ 8-बिट सेल आईडी वैल्यू डालने पर, नतीजे गलत मिलते हैं या कोई नतीजा नहीं मिलता.

एपीआई अनुरोध में इन सीमाओं से बाहर की वैल्यू डालने पर, अनचाहा व्यवहार हो सकता है. Google के पास यह अधिकार है कि वह एपीआई के ज़रिए, संख्या को छोटा कर दे, ताकि वह दस्तावेज़ में बताई गई सीमा के अंदर आ जाए. इसके अलावा, वह radioType में सुधार का सुझाव दे सकता है या जवाब में कोई इंडिकेटर दिए बिना NOT_FOUND नतीजा दिखा सकता है.

एलटीई सेल टावर ऑब्जेक्ट का एक उदाहरण यहां दिया गया है. यह अनुरोध बॉडी का हिस्सा है.

{
  ...

  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

पिछले अनुरोध का जवाब ऐसा दिखता है:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

कैलकुलेट किया जा रहा है newRadioCellId

नए नेटवर्क, जिनके सेल आईडी 32 बिट से ज़्यादा लंबे होते हैं, वे नेटवर्क सेल आईडी को Geolocation API को पास करने के लिए 64-बिट newRadioCellId फ़ील्ड का इस्तेमाल करते हैं.

• एनआर (5G) नेटवर्क, 36-बिट वाले न्यू रेडियो सेल आइडेंटिटी (एनसीआई) का इस्तेमाल करते हैं.
  मान्य सीमा: 0–68719476735.

अनुरोध के मुख्य हिस्से में शामिल, एनआर सेल टावर ऑब्जेक्ट का एक उदाहरण यहां दिया गया है.

{
  ...

  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

पिछले अनुरोध का जवाब ऐसा दिखता है:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट

अनुरोध के मुख्य हिस्से की wifiAccessPoints ऐरे में, दो या उससे ज़्यादा वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट होने चाहिए. ये ऑब्जेक्ट, भौतिक रूप से अलग-अलग स्टेशनरी ऐक्सेस पॉइंट डिवाइसों के बारे में बताते हैं. macAddress फ़ील्ड को भरना ज़रूरी है. अन्य सभी फ़ील्ड में जानकारी देना ज़रूरी नहीं है. यह सेवा, ऐसे ऐक्सेस पॉइंट को अनदेखा करती है जो एक जगह से दूसरी जगह जाते हैं. जैसे, हवाई जहाज़ और ट्रेनों में मौजूद ऐक्सेस पॉइंट.

वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट का एक उदाहरण यहां दिया गया है. यह अनुरोध बॉडी का हिस्सा है.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

पिछले अनुरोध का जवाब ऐसा दिखता है:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

अनुरोध के सैंपल

अगर आपको सैंपल डेटा के साथ Geolocation API आज़माना है, तो नीचे दिए गए JSON को किसी फ़ाइल में सेव करें:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "30:86:2d:c4:29:d0",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    }
  ]
}

इसके बाद, कमांड लाइन से अनुरोध करने के लिए, curl का इस्तेमाल किया जा सकता है:

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

ऊपर दिए गए MAC पतों के लिए मिलने वाला जवाब ऐसा दिखता है:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

इस्तेमाल न किए गए वाई-फ़ाई ऐक्सेस पॉइंट हटाना

macAddress वाले वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट हटाने से, Geolocation API कॉल की सफलता दर को बेहतर बनाया जा सकता है. ये ऑब्जेक्ट, ब्रॉडकास्ट पते (FF:FF:FF:FF:FF:FF) या IANA के लिए रिज़र्व किए गए होते हैं. ये कॉल, वाई-फ़ाई को इनपुट के तौर पर इस्तेमाल करते हैं. अगर फ़िल्टर करने के बाद यह पता चलता है कि Geolocation API कॉल पूरा नहीं हो पाएगा, तो कुछ तरीके अपनाए जा सकते हैं. जैसे, जगह की जानकारी देने वाले पुराने सिग्नल या कमज़ोर सिग्नल वाले वाई-फ़ाई एपी का इस्तेमाल करना. इस तरीके में, आपके ऐप्लिकेशन को जगह की अनुमानित जानकारी देने की ज़रूरत और सटीक जानकारी देने की ज़रूरत के बीच समझौता किया जाता है. साथ ही, इसमें सटीक जानकारी देने और याद रखने की ज़रूरी शर्तों के बीच भी समझौता किया जाता है. फ़िल्टर करने के इन तरीकों से, इनपुट को फ़िल्टर करने का तरीका पता चलता है. हालांकि, इनमें उन बचावों के बारे में नहीं बताया गया है जिन्हें ऐप्लिकेशन इंजीनियर के तौर पर, आपको लागू करना पड़ सकता है.

00:00:5E:00:00:00 और 00:00:5E:FF:FF:FF के बीच के MAC पते, IANA के लिए रिज़र्व किए गए हैं. इनका इस्तेमाल अक्सर नेटवर्क मैनेजमेंट और मल्टीकास्ट फ़ंक्शन के लिए किया जाता है. इसलिए, इनका इस्तेमाल जगह की जानकारी देने वाले सिग्नल के तौर पर नहीं किया जा सकता. आपको एपीआई के इनपुट से भी इन मैक पतों को हटाना होगा.

उदाहरण के लिए, जियोलोकेशन के लिए इस्तेमाल किए जा सकने वाले MAC पते, macs नाम वाली macAddress स्ट्रिंग के ऐरे से इकट्ठा किए जा सकते हैं:

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && m.substr(0, 8).toUpperCase() !== '00:00:5E');
    

इस फ़िल्टर का इस्तेमाल करने पर, सूची में सिर्फ़ 1c:34:56:78:9a:bc आइटम बचे हैं. इस सूची में दो से कम वाई-फ़ाई मैक पते हैं. इसलिए, अनुरोध पूरा नहीं किया जा सकेगा और एचटीटीपी 404 (notFound) रिस्पॉन्स मिलेगा.

जियोलोकेशन से जुड़े जवाब

जियोलोकेशन का अनुरोध पूरा होने पर, JSON फ़ॉर्मैट में जवाब मिलता है. इसमें किसी जगह और उसके दायरे के बारे में जानकारी होती है.

• location: उपयोगकर्ता के अक्षांश और देशांतर के अनुमानित निर्देशांक, डिग्री में. इसमें एक lat और एक lng सबफ़ील्ड होता है.
• accuracy: अनुमानित जगह की जानकारी की सटीक जानकारी, मीटर में. यह दिए गए location के चारों ओर मौजूद सर्कल की त्रिज्या को दिखाता है.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

यह एपीआई, इनपुट सिग्नल के आधार पर जगह की जानकारी और सटीक होने की संभावना का दायरा दिखाता है. एपीआई, जगह की सटीक जानकारी दे सकता है. हालांकि, यह जानकारी कितनी सटीक होगी, यह इन बातों पर निर्भर करता है: जगह की जानकारी देने वाले सोर्स, उपलब्ध सिग्नल की संख्या, घनत्व, और सिग्नल की क्वालिटी. आम तौर पर, आपको ये सटीक रेडियस दिख सकते हैं:

• वाई-फ़ाई ऐक्सेस पॉइंट: अगर अनुरोध में दो या उससे ज़्यादा wifiAccessPoints शामिल हैं, तो आम तौर पर, जगह की सटीक जानकारी के लिए 20 मीटर का दायरा मिलता है. ऐक्सेस पॉइंट की संख्या और सिग्नल की मज़बूती (dBm में मेज़र की जाती है) बढ़ने पर, सटीक नतीजे मिलते हैं. सिग्नल की मज़बूती आम तौर पर -100 से -20 dBm तक होती है.
• सेल टॉवर: अगर वाईफ़ाई की जानकारी उपलब्ध नहीं है या ज़रूरत के हिसाब से नहीं है, तो एपीआई, जगह की जानकारी के लिए cellTowers का इस्तेमाल करता है. सेल टावर टाइप, सिग्नल की क्वालिटी, और नेटवर्क डेंसिटी के हिसाब से, सटीक होने की संभावना में काफ़ी अंतर होता है:
  • मैक्रो सेल (यह सबसे आम टाइप है और इसका इस्तेमाल बड़े इलाके को कवर करने के लिए किया जाता है) से सटीक जानकारी नहीं मिलती. आम तौर पर, यह दायरा सैकड़ों मीटर का होता है. हालांकि, जिन इलाकों में सेल टॉवर की कवरेज कम होती है वहां यह दायरा कई हज़ार मीटर तक हो सकता है. मैक्रो सेल के लिए, आम तौर पर 100 मीटर से कम का सटीक दायरा नहीं मिलता है. आम तौर पर, मज़बूत सिग्नल वाले सेल टावर के लिए, सटीक जानकारी मिलने की संभावना ज़्यादा होती है. आम तौर पर, एलटीई के लिए मज़बूत सिग्नल > -110 dBm (सिग्नल रेंज -140 से -55 dBm), WCDMA के लिए > -100 dBm (सिग्नल रेंज -111 से -53 dBm), CDMA के लिए > -100 dBm (सिग्नल रेंज -120 से -40 dBm), और GSM के लिए > -80 dBm (सिग्नल रेंज -121 से -1 dBm) होते हैं.
  • छोटी सेल (जैसे, फ़ेम्टोसेल, पिकोसेल या इंडोर रिपीटर) से, सेल के आधार पर जगह की सबसे सटीक जानकारी मिलती है. इसकी सटीक दूरी 10 से 30 मीटर के बीच हो सकती है.
• आईपी पते के हिसाब से जगह की जानकारी: अगर considerIp true है और वाई-फ़ाई या सेल टॉवर के सिग्नल की जगह की जानकारी नहीं मिल पा रही है, तो एपीआई, अनुरोध के आईपी पते के आधार पर जगह का अनुमान लगाता है. इस तरीके से, सबसे कम सटीक जानकारी मिलती है. इसमें कई किलोमीटर तक की दूरी शामिल हो सकती है. देखें सटीक होने की संभावना वाला दायरा बहुत बड़ा क्यों है? समस्या हल करने की गाइड में जाकर देखें.