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

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

जगह की जानकारी के अनुरोध, इस यूआरएल पर 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–268435455.
  ध्यान दें: 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–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 बिट से ज़्यादा लंबे होते हैं, वे नेटवर्क सेल आईडी को 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 एपीआई कॉल पूरा नहीं हो पाएगा, तो पुरानी जगह की जानकारी के सिग्नल या कमज़ोर सिग्नल वाले वाई-फ़ाई एपी का इस्तेमाल किया जा सकता है. इस तरीके से, आपके ऐप्लिकेशन को जगह की अनुमानित जानकारी देने की ज़रूरत और सटीक जानकारी देने की ज़रूरत के बीच समझौता किया जाता है. साथ ही, यह जानकारी को वापस पाने की ज़रूरी शर्तों को भी पूरा करता है. फ़िल्टर करने के इन तरीकों से, इनपुट को फ़िल्टर करने का तरीका पता चलता है. हालांकि, इनमें उन सुरक्षा उपायों के बारे में नहीं बताया गया है जिन्हें ऐप्लिकेशन इंजीनियर के तौर पर लागू किया जा सकता है.

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