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

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

जियोलोकेशन के अनुरोध, पीओएसटी तरीके से यहां दिए गए यूआरएल पर भेजे जाते हैं:

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

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

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

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

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

फ़ील्ड JSON का टाइप जानकारी ज़रूरी जानकारी
cellId number (uint32) सेल का यूनीक आइडेंटिफ़ायर. radioType gsm (डिफ़ॉल्ट), cdma, wcdma और lte के लिए ज़रूरी; nr के लिए अस्वीकार कर दिया गया.
नीचे दिया गया सेल आईडी कैलकुलेट करना सेक्शन देखें. इसमें, हर रेडियो टाइप के लिए मान्य वैल्यू रेंज की सूची भी दी गई है.
newRadioCellId number (uint64) एनआर (5G) सेल का यूनीक आइडेंटिफ़ायर. radioType nr के लिए ज़रूरी है; दूसरे टाइप के लिए अस्वीकार किया गया.
नीचे दिया गया RadioCellId का हिसाब लगाना सेक्शन देखें. इसमें फ़ील्ड के लिए, मान्य वैल्यू की रेंज भी दी गई है.
locationAreaCode number (uint32) GSM और डब्ल्यूसीडीएमए नेटवर्क के लिए जगह का एरिया कोड (एलएसी).
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, डब्ल्यूसीडीएमए, एलटीई, और एनआर के लिए एमएनसी है.
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-बिट बेस स्टेशन आईडी (BID) का इस्तेमाल करते हैं. मान्य रेंज: 0–65535.
  • डब्ल्यूसीडीएमए (3G) नेटवर्क, UTRAN/GERAN सेल आइडेंटिटी (UC-ID) का इस्तेमाल करते हैं. यह 28-बिट वाला पूर्णांक वैल्यू है, जो 12-बिट रेडियो नेटवर्क कंट्रोलर आइडेंटिफ़ायर (RNC-ID) और 16-बिट सेल आईडी (सीआईडी) को आपस में जोड़ता है.
    फ़ॉर्मूला: rnc_id << 16 | cid.
    मान्य रेंज: 0–268435455.
    ध्यान दें: डब्ल्यूसीडीएमए नेटवर्क में सिर्फ़ 16-बिट सेल आईडी की वैल्यू बताने से, गलत या शून्य नतीजे मिलते हैं.
  • LTE (4G) नेटवर्क, E-UTRAN सेल आइडेंटिटी (ईसीआई) का इस्तेमाल करते हैं. यह 28-बिट पूर्णांक वैल्यू होती है, जो 20-बिट वाले ई-यूट्राएन नोड बी आइडेंटिफ़ायर (eNBId) और 8-बिट सेल आईडी (सीआईडी) को जोड़ती है.
    फ़ॉर्मूला: enb_id << 8 | cid.
    मान्य रेंज: 0–268435455.
    ध्यान दें: LTE नेटवर्क में सिर्फ़ 8-बिट सेल आईडी की वैल्यू बताने से, गलत या शून्य नतीजे मिलते हैं.

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

यहां LTE सेल टावर ऑब्जेक्ट का एक उदाहरण दिया गया है.

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

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

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

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

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

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

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

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

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

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

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

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

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

उदाहरण के लिए, जियोलोकेशन के लिए इस्तेमाल किए जा सकने वाले 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 बचा रहता है. इस सूची में दो से कम वाई-फ़ाई MAC पते हैं. इसलिए, अनुरोध स्वीकार नहीं किया जाएगा और एचटीटीपी 404 (notFound) रिस्पॉन्स मिलेगा.

भौगोलिक-स्थान से जुड़े जवाब

जियोलोकेशन का अनुरोध पूरा होने पर, JSON के फ़ॉर्मैट में जवाब मिलता है. इसमें जगह और दायरा तय होता है.

  • location: उपयोगकर्ता के अनुमानित अक्षांश और देशांतर निर्देशांक, डिग्री में. इसमें एक lat और एक lng सबफ़ील्ड शामिल है.
  • accuracy: अनुमानित जगह की सटीक जानकारी, मीटर में. यह दिए गए location के आस-पास सर्कल का दायरा दिखाता है.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}