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

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

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

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

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

cellId की गिनती करना

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

  • GSM (2G) नेटवर्क, 16-बिट सेल आईडी (सीआईडी) का इस्तेमाल वैसे ही करते हैं. मान्य रेंज: 0 से 65,535.
  • सीडीएमए (2G) नेटवर्क, 16-बिट बेस स्टेशन आईडी (बीआईडी) का इस्तेमाल वैसे ही करते हैं जैसे वह है. मान्य रेंज: 0 से 65,535.
  • 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-बिट सेल आईडी (CID) को जोड़ा जाता है.
    फ़ॉर्मूला: enb_id << 8 | cid.
    मान्य रेंज: 0 से 268435455.
    ध्यान दें: LTE नेटवर्क में सिर्फ़ 8-बिट सेल आईडी वैल्यू डालने पर, गलत या शून्य नतीजे मिलते हैं.

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

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

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

newRadioCellId का हिसाब लगाना

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

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

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

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

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

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

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

अनुरोध के सैंपल

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

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

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

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

जगह की जानकारी से जुड़े जवाब

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

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