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

भौगोलिक स्थान के अनुरोध

जियोलोकेशन के अनुरोध 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 के लिए 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 के लिए एमएनसी है.
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-बिट बेस स्टेशन आईडी (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-बिट सेल आईडी (सीआईडी) को जोड़ती है.
    फ़ॉर्मूला: 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 में मापी गई है. वाई-फ़ाई ऐक्सेस पॉइंट के लिए, 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 बिट को 2 से दिखाया जाता है, जिसे 02:00:00:00:00:00 में दिखाया जाता है. ब्रॉडकास्ट 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 स्ट्रिंग की श्रेणी से इकट्ठा किए जा सकते हैं:

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
}