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

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

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

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

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

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

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

Geolocation API के अनुरोध बॉडी का उदाहरण यहां दिया गया है.

{
  "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 आज़माना है, तो नीचे दिए गए जेएसओएन को फ़ाइल में सेव करें:

{
  "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
}

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

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

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

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
}