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

जगह की जानकारी के अनुरोध

जगह की जानकारी के अनुरोध, 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 का हिसाब लगाया जा रहा है

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

• जीएसएम (2G) नेटवर्क, 16-बिट वाले सेल आईडी (सीआईडी) का इस्तेमाल करते हैं. मान्य रेंज: 0–65535.
• सीडीएमए (2G) नेटवर्क, 16-बिट बेस स्टेशन आईडी (बीआईडी) का इस्तेमाल करते हैं. मान्य रेंज: 0–65535.
• WCDMA (3G) नेटवर्क, यूटीआरएएन/जीईआरएएन सेल आइडेंटिटी (यूसी-आईडी) का इस्तेमाल करते हैं. यह 28-बिट की पूर्णांक वैल्यू होती है. इसमें 12-बिट का रेडियो नेटवर्क कंट्रोलर आइडेंटिफ़ायर (आरएनसी-आईडी) और 16-बिट का सेल आईडी (सीआईडी) शामिल होता है.
  फ़ॉर्मूला: rnc_id << 16 | cid.
  मान्य रेंज: 0–268435455.
  ध्यान दें: WCDMA नेटवर्क में सिर्फ़ 16-बिट सेल आईडी वैल्यू देने पर, गलत या शून्य नतीजे मिलते हैं.
• एलटीई (4G) नेटवर्क, ई-यूटीआरएएन सेल आइडेंटिटी (ईसीआई) का इस्तेमाल करते हैं. यह 28-बिट की पूर्णांक वैल्यू होती है. इसमें 20-बिट ई-यूटीआरएएन नोड बी आइडेंटिफ़ायर (ईएनबीआईडी) और 8-बिट सेल आईडी (सीआईडी) को जोड़ा जाता है.
  फ़ॉर्मूला: enb_id << 8 | cid.
  मान्य रेंज: 0–268435455.
  ध्यान दें: एलटीई नेटवर्क में सिर्फ़ 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 बिट से ज़्यादा लंबे होते हैं वे 64-बिट वाले newRadioCellId फ़ील्ड का इस्तेमाल करते हैं. इससे, नेटवर्क सेल आईडी को Geolocation API को पास किया जाता है.

• एनआर (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"

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

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

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

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

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

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