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

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

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

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

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

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

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

फ़ील्ड JSON टाइप ब्यौरा नोट
homeMobileCountryCode number (uint32) डिवाइस के होम नेटवर्क का मोबाइल देश कोड (एमसीसी). radioType gsm (डिफ़ॉल्ट), wcdma, lte, और nr के लिए इस्तेमाल किया जा सकता है; cdma के लिए इस्तेमाल नहीं किया जा सकता.
मान्य रेंज: 0–999.
homeMobileNetworkCode number (uint32) डिवाइस के होम नेटवर्क का मोबाइल नेटवर्क कोड. यह जीएसएम, डब्ल्यूसीडीएमए, एलटीई, और एनआर के लिए एमएनसी है.
सीडीएमए, सिस्टम आईडी (एसआईडी) का इस्तेमाल करता है		 एमएनसी के लिए मान्य रेंज: 0–999.
एसआईडी के लिए मान्य रेंज: 0 से 32767.
radioType string मोबाइल रेडियो का टाइप. इस्तेमाल की जा सकने वाली वैल्यू gsm, cdma, wcdma, lte, और nr हैं. यह फ़ील्ड भरना ज़रूरी नहीं है. हालांकि, अगर क्लाइंट को रेडियो टाइप की जानकारी है, तो इसे हमेशा शामिल किया जाना चाहिए.
अगर फ़ील्ड को शामिल नहीं किया जाता है, तो Geolocation API डिफ़ॉल्ट रूप से gsm पर सेट हो जाता है. अगर रेडियो टाइप की जानकारी गलत है, तो इससे अमान्य या शून्य नतीजे मिलेंगे.
carrier string कैरियर का नाम.
considerIp boolean इससे यह तय होता है कि वाई-फ़ाई और सेल टावर के सिग्नल न होने, खाली होने या डिवाइस की जगह की जानकारी का अनुमान लगाने के लिए काफ़ी न होने पर, आईपी जियोलोकेशन पर वापस जाना है या नहीं. डिफ़ॉल्ट रूप से, यह true पर सेट होता है. considerIp को false पर सेट करें, ताकि फ़ॉलबैक से बचा जा सके.
cellTowers array सेल टावर ऑब्जेक्ट का कलेक्शन. नीचे दिया गया सेल टावर ऑब्जेक्ट सेक्शन देखें.
wifiAccessPoints array वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट का कलेक्शन. नीचे दिया गया वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट सेक्शन देखें.

यहां 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 कलेक्शन में, शून्य या उससे ज़्यादा सेल टावर ऑब्जेक्ट होते हैं.

फ़ील्ड JSON टाइप ब्यौरा नोट
cellId number (uint32) सेल का यूनीक आइडेंटिफ़ायर. radioType gsm (डिफ़ॉल्ट), cdma, wcdma, और lte के लिए ज़रूरी है; nr के लिए अस्वीकार किया गया.
नीचे दिया गया cellId कैलकुलेट करना सेक्शन देखें. इसमें हर रेडियो टाइप के लिए, मान्य वैल्यू की रेंज भी दी गई है.
newRadioCellId number (uint64) एनआर (5G) सेल का यूनीक आइडेंटिफ़ायर. radioType nr के लिए ज़रूरी है; अन्य टाइप के लिए अस्वीकार किया गया.
नीचे दिया गया newRadioCellId का हिसाब लगाना सेक्शन देखें. इसमें इस फ़ील्ड के लिए मान्य वैल्यू की रेंज भी दी गई है.
locationAreaCode number (uint32) जीएसएम और डब्ल्यूसीडीएमए नेटवर्क के लिए, लोकेशन एरिया कोड (एलएसी).
सीडीएमए नेटवर्क के लिए नेटवर्क आईडी (एनआईडी).
एलटीई और एनआर नेटवर्क के लिए ट्रैकिंग एरिया कोड (टीएसी).		 ज़रूरी है radioType gsm (डिफ़ॉल्ट) और cdma के लिए, अन्य वैल्यू के लिए ज़रूरी नहीं है.
gsm, cdma, wcdma, और lte के साथ मान्य रेंज: 0–65535.
nr के साथ मान्य रेंज: 0–16777215.
mobileCountryCode number (uint32) सेल टावर का मोबाइल देश कोड (एमसीसी). radioType gsm (डिफ़ॉल्ट), wcdma, lte, और nr के लिए ज़रूरी है; cdma के लिए इस्तेमाल नहीं किया जाता.
मान्य रेंज: 0–999.
mobileNetworkCode number (uint32) सेल टावर का मोबाइल नेटवर्क कोड. यह जीएसएम, डब्ल्यूसीडीएमए, एलटीई, और एनआर के लिए एमएनसी है.
सीडीएमए, सिस्टम आईडी (एसआईडी) का इस्तेमाल करता है.		 ज़रूरी है.
एमएनसी के लिए मान्य रेंज: 0–999.
एसआईडी के लिए मान्य रेंज: 0 से 32767.

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

फ़ील्ड JSON टाइप ब्यौरा नोट
age number (uint32) इस सेल के प्राइमरी होने के बाद से अब तक बीते मिलीसेकंड की संख्या. अगर उम्र 0 है, तो cellId या newRadioCellId मौजूदा मेज़रमेंट को दिखाता है.
signalStrength number (double) रेडियो सिग्नल की क्षमता को dBm में मापा जाता है.
timingAdvance number (double) टाइमिंग ऐडवांस की वैल्यू.

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 फ़ील्ड भरना ज़रूरी है. अन्य सभी फ़ील्ड भरना ज़रूरी नहीं है. यह सेवा, एक जगह से दूसरी जगह जाने वाले ऐक्सेस पॉइंट को अनदेखा करती है. जैसे, हवाई जहाज़ और ट्रेन में मौजूद ऐक्सेस पॉइंट.

फ़ील्ड JSON टाइप ब्यौरा नोट
macAddress string वाई-फ़ाई नोड का मैक पता. आम तौर पर, इसे बीएसएस, बीएसएसआईडी या मैक पता कहा जाता है. ज़रूरी है.कोलन से अलग की गई (:) हेक्साडेसिमल स्ट्रिंग.
एपीआई का इस्तेमाल करके, सिर्फ़ यूनिवर्सली-एडमिनिस्टर्ड मैक पतों का पता लगाया जा सकता है. अन्य मैक पतों को बिना किसी सूचना के हटा दिया जाता है. इससे, एपीआई अनुरोध में कोई जानकारी नहीं रह जाती. ज़्यादा जानकारी के लिए, बेकार वाई-फ़ाई ऐक्सेस पॉइंट हटाना लेख पढ़ें.
signalStrength number (double) सिग्नल की मौजूदा क्षमता, जिसे डीबीएम में मापा जाता है. वाई-फ़ाई ऐक्सेस पॉइंट के लिए, dBm वैल्यू आम तौर पर -35 या इससे कम होती हैं. साथ ही, ये -128 से -10 dBm के बीच होती हैं. माइनस का निशान ज़रूर शामिल करें.
-10 dBm से ज़्यादा की वैल्यू के लिए, एपीआई NOT FOUND दिखाता है.
age number (uint32) इस ऐक्सेस पॉइंट का पता चलने के बाद से अब तक बीते मिलीसेकंड की संख्या.
channel number (uint32) वह चैनल जिसके ज़रिए क्लाइंट, ऐक्सेस पॉइंट से कम्यूनिकेट कर रहा है.
signalToNoiseRatio number (double) सिग्नल और शोर का मौजूदा अनुपात. इसे dB में मापा जाता है.

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

{
  ...
  
  "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 स्ट्रिंग के कलेक्शन से इकट्ठा किए जा सकते हैं:

Java
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")));
Python
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')]
JavaScript
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 है और वाई-फ़ाई या सेल टावर के सिग्नल से जगह की जानकारी नहीं मिल पाती है, तो एपीआई, अनुरोध के आईपी पते के आधार पर जगह की जानकारी का अनुमान लगाता है. इस तरीके से सबसे कम सटीक जानकारी मिलती है. इसमें रेडियस हज़ारों मीटर तक हो सकता है. देखें कि सटीक जगह की जानकारी का दायरा बहुत बड़ा क्यों है? समस्या हल करने की गाइड में दी गई है.