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

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

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

स्थानीय तौर पर मैनेज किए जाने वाले MAC पते, एपीआई के लिए जगह की जानकारी देने वाले सिग्नल के तौर पर काम नहीं करते. इसलिए, इन्हें अनुरोधों से हटा दिया जाता है. ऐसे मैक पतों को हटाया जा सकता है.इसके लिए, यह पक्का करें कि macAddress के सबसे अहम बाइट का दूसरा सबसे कम अहम बिट 0 हो. उदाहरण के लिए, 02:00:00:00:00:00 में 2 से दिखाया गया 1 बिट. ब्रॉडकास्ट MAC पता (FF:FF:FF:FF:FF:FF) एक ऐसा MAC पता है जिसे इस फ़िल्टर की मदद से आसानी से हटाया जा सकता है.

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

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

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

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (0 == (2 & int(m[1], 16)) and m[:8].upper() != '00:00:5E')]
    

macs = ['12:34:56:78:9a:bc', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => 0 === (2 & Number.parseInt(m[1], 16))
                           && 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
}