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

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

जियोलोकेशन के अनुरोध, 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.
• डब्ल्यूसीडीएमए (3G) नेटवर्क, यूटीआरएएन/जीईआरएएन सेल आइडेंटिटी (यूसी-आईडी) का इस्तेमाल करते हैं. यह 28-बिट इंटिजर वैल्यू है. इसमें 12-बिट रेडियो नेटवर्क कंट्रोलर आइडेंटिफ़ायर (आरएनसी-आईडी) और 16-बिट सेल आईडी (सीआईडी) शामिल होते हैं.
  फ़ॉर्मूला: rnc_id << 16 | cid.
  मान्य रेंज: 0–268435455.
  ध्यान दें: डब्ल्यूसीडीएमए नेटवर्क में सिर्फ़ 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` की गणना करना 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"

ऊपर दिए गए एमएसी (मीडिया ऐक्सेस कंट्रोल) पतों का जवाब ऐसा दिखता है:

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

काम के न रहने वाले वाई-फ़ाई ऐक्सेस पॉइंट को हटाना

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

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

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

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