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

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

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

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

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

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

cellId की गणना की जा रही है

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

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

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

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

{
  "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 में मापी गई है. WiFi ऐक्सेस पॉइंट के लिए, dBm वैल्यू आम तौर पर -35 या उससे कम होती है और यह -128 से -10 dBm के बीच होती है. माइनस का निशान ज़रूर शामिल करें.
age number (uint32) इस ऐक्सेस पॉइंट का पता चलने के बाद से अब तक मिले मिलीसेकंड.
channel number (uint32) वह चैनल जिस पर क्लाइंट ऐक्सेस पॉइंट से संपर्क कर रहा है.
signalToNoiseRatio number (double) मौजूदा सिग्नल और शोर का अनुपात dB में मापा गया है.

वाई-फ़ाई ऐक्सेस पॉइंट ऑब्जेक्ट का एक उदाहरण नीचे दिया गया है.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

अनुरोध के नमूने

अगर आपको सैंपल डेटा के साथ जियोलोकेशन एपीआई आज़माना है, तो नीचे दिए गए JSON को फ़ाइल में सेव करें:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "94:b4:0f:fd:c1:40",
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

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

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

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

JavaScript
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
}