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

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

जियोलोकेशन की जानकारी के लिए अनुरोध, 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) डिवाइस के होम नेटवर्क के लिए, मोबाइल नेटवर्क कोड. यह GSM, WCDMA, LTE, और NR के लिए एमएनसी है.
CDMA, सिस्टम आईडी (एसआईडी) का इस्तेमाल करता है		 एमएनसी के लिए मान्य रेंज: 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 वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट का कलेक्शन. नीचे, वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट वाला सेक्शन देखें.

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

फ़ील्ड JSON टाइप ब्यौरा नोट
cellId number (uint32) सेल का यूनीक आइडेंटिफ़ायर. ज़रूरी है radioType gsm (डिफ़ॉल्ट), cdma, wcdma और lte के लिए; अस्वीकार किया गया nr के लिए.
नीचे, `cellId` की वैल्यू तय करने का तरीका वाला सेक्शन देखें. इसमें हर रेडियो टाइप के लिए, मान्य वैल्यू की रेंज भी दी गई है.
newRadioCellId number (uint64) एनआर (5G) सेल का यूनीक आइडेंटिफ़ायर. ज़रूरी है radioType nr के लिए; अन्य टाइप के लिए अस्वीकार किया गया.
नीचे, `newRadioCellId` की वैल्यू तय करने का तरीका वाला सेक्शन देखें. इसमें इस फ़ील्ड के लिए, मान्य वैल्यू की रेंज भी दी गई है.
locationAreaCode number (uint32) GSM और WCDMA नेटवर्क के लिए, लोकेशन एरिया कोड (एलएसी).
CDMA नेटवर्क के लिए, नेटवर्क आईडी (एनआईडी).
LTE और NR नेटवर्क के लिए, ट्रैकिंग एरिया कोड (टीएसी).		 ज़रूरी है radioType gsm (डिफ़ॉल्ट) और cdma के लिए. अन्य वैल्यू के लिए, इसमें जानकारी देना ज़रूरी नहीं है.
gsm, cdma, wcdma, और lte के साथ मान्य रेंज: 0–65535.
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–32767.

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

फ़ील्ड 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-बिट बेस स्टेशन आईडी (बीआईडी) का इस्तेमाल करते हैं. मान्य रेंज: 0–65535.
  • WCDMA (3G) नेटवर्क, यूटीआरएएन/GERAN सेल आइडेंटिटी (यूसी-आईडी) का इस्तेमाल करते हैं. यह 28-बिट इंटिजर वैल्यू है, जो 12-बिट रेडियो नेटवर्क कंट्रोलर आइडेंटिफ़ायर (आरएनसी-आईडी) और 16-बिट सेल आईडी (सीआईडी) को जोड़कर बनती है.
    फ़ॉर्मूला: rnc_id << 16 | cid.
    मान्य रेंज: 0–268435455.
    ध्यान दें: WCDMA नेटवर्क में सिर्फ़ 16-बिट सेल आईडी की वैल्यू तय करने पर, गलत या शून्य नतीजे मिलते हैं.
  • LTE (4G) नेटवर्क, ई-यूटीआरएएन सेल आइडेंटिटी (ईसीआई) का इस्तेमाल करते हैं. यह 28-बिट इंटिजर वैल्यू है, जो 20-बिट ई-यूटीआरएएन नोड बी आइडेंटिफ़ायर (ईएनबीआईडी) और 8-बिट सेल आईडी (सीआईडी) को जोड़कर बनती है.
    फ़ॉर्मूला: enb_id << 8 | cid.
    मान्य रेंज: 0–268435455.
    ध्यान दें: LTE नेटवर्क में सिर्फ़ 8-बिट सेल आईडी की वैल्यू तय करने पर, गलत या शून्य नतीजे मिलते हैं.

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

यहां LTE सेल टॉवर ऑब्जेक्ट का एक उदाहरण दिया गया है. यह अनुरोध के मुख्य भागका हिस्सा है.

{
  ...

  "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` की वैल्यू तय करना 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 फ़ील्ड में जानकारी देना ज़रूरी है. अन्य सभी फ़ील्ड में जानकारी देना ज़रूरी नहीं है. यह सेवा, ऐसे ऐक्सेस पॉइंट को अनदेखा करती है जो मूव करते हैं. जैसे, हवाई जहाज़ों और ट्रेनों में मौजूद ऐक्सेस पॉइंट.

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

ऊपर दिए गए अनुरोध का जवाब ऐसा दिखता है:

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

ऊपर दिए गए एमएसी (मीडिया ऐक्सेस कंट्रोल) पतों का जवाब ऐसा दिखता है:

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

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

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

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

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

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