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

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

जियोलोकेशन के अनुरोध, 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.
SID के लिए मान्य रेंज: 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": "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 नेटवर्क के लिए नेटवर्क आईडी (एनआईडी).
एलटीई और एनआर नेटवर्क के लिए ट्रैकिंग एरिया कोड (टीएसी).		 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.
SID के लिए मान्य रेंज: 0–32767.

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

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

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–26,84,35,455.
    ध्यान दें: 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–26,84,35,455.
    ध्यान दें: एलटीई नेटवर्क में सिर्फ़ 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 फ़ील्ड को भरना ज़रूरी है. अन्य सभी फ़ील्ड में जानकारी देना ज़रूरी नहीं है. यह सेवा, ऐसे ऐक्सेस पॉइंट को अनदेखा करती है जो एक जगह से दूसरी जगह जाते हैं. जैसे, हवाई जहाज़ और ट्रेनों में मौजूद ऐक्सेस पॉइंट.

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

ऊपर दिए गए MAC पतों के लिए मिलने वाला जवाब ऐसा दिखता है:

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

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

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

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

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

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