खास जानकारी

सुविधा के बारे में जानकारी

जियोलोकेशन एपीआई सेल टावर और वाई-फ़ाई नोड से जुड़ी जानकारी के आधार पर उस जगह का सटीक डेटा देता है जिसकी पहचान मोबाइल नेटवर्क क्लाइंट कर सकता है. इस दस्तावेज़ में उस प्रोटोकॉल के बारे में बताया गया है जिसका इस्तेमाल सर्वर पर इस डेटा को भेजने और क्लाइंट को रिस्पॉन्स देने के लिए किया जाता है.

POST का इस्तेमाल करके, एचटीटीपीएस पर बातचीत की जाती है. अनुरोध और जवाब, दोनों का फ़ॉर्मैट JSON के तौर पर है. दोनों का कॉन्टेंट application/json है.

शुरू करने से पहले

जियोलोकेशन एपीआई के साथ डेवलप करने से पहले, पुष्टि करने से जुड़ी ज़रूरी शर्तें (एपीआई की कुंजी होना ज़रूरी है) और एपीआई के इस्तेमाल और बिलिंग से जुड़ी जानकारी देखें. आपको अपने प्रोजेक्ट पर बिलिंग की सुविधा चालू करनी होगी.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

वाई-फ़ाई ऐक्सेस बिंदु ऑब्जेक्ट

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

फ़ील्ड JSON का प्रकार जानकारी ज़रूरी जानकारी
macAddress string वाई-फ़ाई नोड का MAC पता. इसे आम तौर पर BSS, BSSID या 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 फ़ॉर्मैट में जवाब मिलेगा, जिससे जगह और दायरे का पता चलेगा.

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

गड़बड़ियां

अगर कोई गड़बड़ी होती है, तो स्टैंडर्ड फ़ॉर्मैट की गड़बड़ी वाले जवाब का मुख्य हिस्सा दिखाया जाएगा. साथ ही, एचटीटीपी स्टेटस कोड, गड़बड़ी की स्थिति पर सेट किया जाएगा.

इस जवाब के साथ, error ऑब्जेक्ट वाला एक ऑब्जेक्ट होता है, जिसमें ये कुंजियां होती हैं:

  • code: यह जवाब की एचटीटीपी स्थिति के जैसा ही है.
  • message: गड़बड़ी के बारे में कम शब्दों में जानकारी.
  • errors: होने वाली गड़बड़ियों की सूची. हर गड़बड़ी में एक गड़बड़ी (reason) और एक छोटी सी जानकारी (message) के लिए एक आइडेंटिफ़ायर होता है.

उदाहरण के लिए, अमान्य JSON भेजने पर यह गड़बड़ी दिखेगी:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

संभावित त्रुटियों में शामिल हैं:

वजह डोमेन एचटीटीपी स्टेटस कोड जानकारी
dailyLimitExceeded usageLimits 403 आपने रोज़ की तय सीमा पूरी कर ली है.
keyInvalid usageLimits 400 आपकी API कुंजी जियोलोकेशन एपीआई के लिए मान्य नहीं है. कृपया पक्का करें कि आपने पूरी कुंजी शामिल की हो और आपको मुफ़्त में एपीआई खरीदने की सुविधा मिली हो या आपने बिना किसी शुल्क के कोटा पाने के लिए, एपीआई को चालू और चालू किया हो.
userRateLimitExceeded usageLimits 403 आपने Google Cloud Console में कॉन्फ़िगर करने के लिए तय सीमा पार कर ली है. आम तौर पर, इस सीमा को हर दिन के अनुरोधों, हर 100 सेकंड के अनुरोधों, और हर उपयोगकर्ता के हिसाब से हर 100 सेकंड के हिसाब से सेट किया जाता है. इस सीमा को इस तरह से कॉन्फ़िगर किया जाना चाहिए कि यह उपयोगकर्ताओं के एक या छोटे ग्रुप को, रोज़ के लिए आपका काम खत्म करने से रोक सके. साथ ही, यह सभी उपयोगकर्ताओं को अब भी ऐक्सेस दे सके. इन सीमाओं को कॉन्फ़िगर करने के लिए, कैपिंग एपीआई के इस्तेमाल से जुड़ी जानकारी देखें.
notFound geolocation 404 अनुरोध मान्य था, लेकिन कोई नतीजा नहीं मिला.
parseError global 400 अनुरोध का मुख्य भाग मान्य JSON नहीं है. हर फ़ील्ड की जानकारी के लिए अनुरोध का मुख्य हिस्सा सेक्शन देखें.

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

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

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "84:d4:7e:f6:99:64",
      "signalStrength": -54,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f6:99:71",
      "signalStrength": -43,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f7:21:35",
      "signalStrength": -32,
      "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.4237423,
      "lng": -122.0915814
  },
  "accuracy": 20
}

(अगर आपके पास एपीआई कुंजी नहीं है, तो एपीआई कुंजी पाएं देखें.)

अतिरिक्त टेस्टिंग के लिए, आप Android के लिए Places SDK टूल और Android लोकेशन एपीआई का इस्तेमाल करके अपने Android डिवाइस से जानकारी इकट्ठा कर सकते हैं. इसके अलावा, आप iOS के लिए SDK टूल के लिए SDK टूल का इस्तेमाल करके, अपने iOS डिवाइस से जानकारी इकट्ठा कर सकते हैं.

अक्सर पूछे जाने वाले सवाल

मुझे अपने भौगोलिक स्थान के रिस्पॉन्स में accuracy का बहुत बड़ा दायरा क्यों दिख रहा है?

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

इस समस्या की पुष्टि करने के लिए, अपने अनुरोध में considerIp को false पर सेट करें. अगर जवाब 404 है, तो आपने पुष्टि की है कि आपके wifiAccessPoints और cellTowers ऑब्जेक्ट का भौगोलिक स्थान नहीं बदला जा सका.