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

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

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

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

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

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

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

जियोलोकेशन एपीआई के अनुरोध बॉडी का उदाहरण नीचे दिया गया है.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "gsm",
  "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 फ़ील्ड का इस्तेमाल करते हैं.

• GSM (2G) नेटवर्क, 16-बिट सेल आईडी (सीआईडी) का इस्तेमाल वैसे ही करते हैं. मान्य रेंज: 0 से 65,535.
• सीडीएमए (2G) नेटवर्क, 16-बिट बेस स्टेशन आईडी (बीआईडी) का इस्तेमाल वैसे ही करते हैं. मान्य रेंज: 0 से 65,535.
• WCDMA (3G) नेटवर्क, UTRAN/GERAN सेल आइडेंटिटी (UC-ID) का इस्तेमाल करते हैं. यह 28-बिट वाली एक पूर्णांक वैल्यू होती है, जिसमें 12-बिट रेडियो नेटवर्क कंट्रोलर आइडेंटिफ़ायर (RNC-ID) और 16-बिट सेल आईडी (CID) को जोड़ा जाता है.
  फ़ॉर्मूला: rnc_id << 16 | cid.
  मान्य रेंज: 0 से 268435455.
  ध्यान दें: WCDMA नेटवर्क में सिर्फ़ 16-बिट सेल आईडी वैल्यू डालने पर, गलत या शून्य नतीजे मिलते हैं.
• LTE (4G) नेटवर्क, E-UTRAN सेल आइडेंटिटी (ECI) का इस्तेमाल करते हैं. यह 28-बिट की पूर्णांक वैल्यू होती है, जिसमें 20-बिट E-UTRAN नोड B आइडेंटिफ़ायर (eNBId) और 8-बिट सेल आईडी (CID) को जोड़ा जाता है.
  फ़ॉर्मूला: enb_id << 8 | cid.
  मान्य रेंज: 0 से 268435455.
  ध्यान दें: LTE नेटवर्क में सिर्फ़ 8-बिट सेल आईडी वैल्यू डालने पर, गलत या शून्य नतीजे मिलते हैं.

एपीआई अनुरोध में इन सीमाओं से बाहर की वैल्यू डालने पर, अनिश्चित व्यवहार हो सकता है. एपीआई, Google के विवेक के आधार पर, संख्या को छोटा कर सकता है, ताकि वह दस्तावेज़ में दी गई सीमा में फ़िट हो सके. इसके अलावा, वह radioType में सुधार का अनुमान लगा सकता है या रिस्पॉन्स में किसी भी इंडिकेटर के बिना NOT_FOUND नतीजा दिखा सकता है.

एलटीई सेल टावर ऑब्जेक्ट का उदाहरण नीचे दिया गया है.

{
  "cellTowers": [
    {
      "cellId": 170402199,
      "locationAreaCode": 35632,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
      "timingAdvance": 15
    }
  ]
}

newRadioCellId का हिसाब लगाना

नए नेटवर्क जिनके सेल आईडी 32 बिट से ज़्यादा लंबे होते हैं वे नेटवर्क सेल आईडी को Geolocation API को पास करने के लिए, 64-बिट newRadioCellId फ़ील्ड का इस्तेमाल करते हैं.

• एनआर (5G) नेटवर्क, 36-बिट न्यू रेडियो सेल आइडेंटिटी (एनसीआई) का इस्तेमाल वैसे ही करते हैं जैसे वह है.
  मान्य रेंज: 0–68719476735.

एनआर सेल टावर ऑब्जेक्ट का उदाहरण नीचे दिया गया है.

{
  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट

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

वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट का उदाहरण नीचे दिया गया है.

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

अनुरोध के सैंपल

अगर आपको सैंपल डेटा के साथ 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
}

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

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

स्थानीय तौर पर मैनेज किए जाने वाले 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 पतों को, macs नाम वाली macAddress स्ट्रिंग के ऐरे से इकट्ठा किया जा सकता है:

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
}