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

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

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

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

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

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

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

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

cellId को कैलकुलेट किया जा रहा है

एनआर (5G) से पहले के रेडियो टाइप, नेटवर्क सेल आईडी को Geolocation API में भेजने के लिए, 32-बिट cellId फ़ील्ड का इस्तेमाल करते हैं.

  • GSM (2G) नेटवर्क 16-बिट सेल आईडी (सीआईडी) का इस्तेमाल करते हैं. मान्य रेंज: 0–65535.
  • CDMA (2G) नेटवर्क, 16-बिट बेस स्टेशन आईडी (BID) का इस्तेमाल करते हैं. मान्य रेंज: 0–65535.
  • 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 ज़रूरी है; अन्य सभी फ़ील्ड ज़रूरी नहीं हैं.

फ़ील्ड JSON टाइप ब्यौरा नोट
macAddress string वाई-फ़ाई नोड का एमएसी पता. इसे आम तौर पर बीएसएस, बीएसएसआईडी या मैक पता कहा जाता है. ज़रूरी है.कोलन से अलग की गई (:) हेक्साडेसिमल स्ट्रिंग.
एपीआई की मदद से, सिर्फ़ दुनिया भर में मैनेज किए जाने वाले MAC पते ढूंढे जा सकते हैं. अन्य एमएसी पते चुपचाप हटा दिए जाते हैं. इससे एपीआई अनुरोध, पूरी तरह से खाली हो सकता है. ज़्यादा जानकारी के लिए, बेकार वाई-फ़ाई ऐक्सेस पॉइंट छोड़ना देखें.
signalStrength number (double) सिग्नल की मौजूदा क्वालिटी को dBm में मेज़र किया जाता है. वाई-फ़ाई ऐक्सेस पॉइंट के लिए, dBm वैल्यू आम तौर पर -35 या उससे कम होती हैं. इनकी रेंज -128 से -10 dBm तक होती है. माइनस का निशान ज़रूर शामिल करें.
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
}

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

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

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

Java
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")));
Python
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')]
JavaScript
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
}