ভৌগলিক অবস্থান অনুরোধ এবং প্রতিক্রিয়া

ভৌগোলিক অবস্থানের অনুরোধ

ভূ-অবস্থানের অনুরোধগুলি POST ব্যবহার করে নিম্নলিখিত URL-এ পাঠানো হয়:

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

আপনার অনুরোধে একটি কী উল্লেখ করতে হবে, যা একটি key প্যারামিটারের মান হিসেবে অন্তর্ভুক্ত থাকবে। key হল আপনার অ্যাপ্লিকেশনের API কী। এই কীটি কোটা পরিচালনার উদ্দেশ্যে আপনার অ্যাপ্লিকেশনটিকে সনাক্ত করে। কীভাবে একটি কী পেতে হয় তা শিখুন।

অনুরোধের মূল অংশ

অনুরোধের মূল অংশটি অবশ্যই JSON হিসেবে ফর্ম্যাট করতে হবে। যদি অনুরোধের মূল অংশটি অন্তর্ভুক্ত না করা হয়, তাহলে অনুরোধের অবস্থানের IP ঠিকানার উপর ভিত্তি করে ফলাফলগুলি ফেরত পাঠানো হবে। নিম্নলিখিত ক্ষেত্রগুলি সমর্থিত, এবং অন্যথায় উল্লেখ না করা পর্যন্ত সমস্ত ক্ষেত্র ঐচ্ছিক:

মাঠ JSON টাইপ বিবরণ মন্তব্য
homeMobileCountryCode number ( uint32 ) ডিভাইসের হোম নেটওয়ার্কের জন্য মোবাইল কান্ট্রি কোড (MCC)। radioType gsm (ডিফল্ট), wcdma , lte এবং nr এর জন্য সমর্থিত ; cdma এর জন্য ব্যবহৃত হয় না।
বৈধ পরিসর: ০–৯৯৯।
homeMobileNetworkCode number ( uint32 ) ডিভাইসের হোম নেটওয়ার্কের জন্য মোবাইল নেটওয়ার্ক কোড। এটি GSM, WCDMA, LTE এবং NR এর জন্য MNC।
সিডিএমএ সিস্টেম আইডি (এসআইডি) ব্যবহার করে		 বহুজাতিক কোম্পানির জন্য বৈধ পরিসর: ০–৯৯৯।
SID এর জন্য বৈধ পরিসর: 0–32767।
radioType string মোবাইল রেডিও টাইপ। সমর্থিত মানগুলি হল gsm , cdma , wcdma , lte এবং nr । যদিও এই ক্ষেত্রটি ঐচ্ছিক, ক্লায়েন্ট যদি রেডিও টাইপটি জানেন তবে এটি সর্বদা অন্তর্ভুক্ত করা উচিত ।
যদি ক্ষেত্রটি বাদ দেওয়া হয়, তাহলে Geolocation API ডিফল্টভাবে gsm তে চলে যাবে, যার ফলে যদি ধরে নেওয়া রেডিও টাইপটি ভুল হয় তাহলে ফলাফল অবৈধ হবে অথবা শূন্য হবে।
carrier string বাহকের নাম।
considerIp boolean ওয়াইফাই এবং সেল টাওয়ার সিগন্যাল অনুপস্থিত, খালি, অথবা ডিভাইসের অবস্থান অনুমান করার জন্য পর্যাপ্ত না থাকলে IP জিওলোকেশনে ফিরে যেতে হবে কিনা তা নির্দিষ্ট করে। ডিফল্ট হিসেবে true আছে। আবার পতন রোধ করতে considerIp কে false হিসেবে সেট করুন।
cellTowers array সেল টাওয়ারের বস্তুর একটি বিন্যাস। নীচের সেল টাওয়ার অবজেক্টস বিভাগটি দেখুন।
wifiAccessPoints array ওয়াইফাই অ্যাক্সেস পয়েন্ট অবজেক্টের একটি অ্যারে। নীচের ওয়াইফাই অ্যাক্সেস পয়েন্ট অবজেক্ট বিভাগটি দেখুন।

জিওলোকেশন এপিআই অনুরোধের একটি উদাহরণ নীচে দেখানো হয়েছে।

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "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 ) 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 ০–১৬৭৭৭২১৫।
mobileCountryCode number ( uint32 ) সেল টাওয়ারের মোবাইল কান্ট্রি কোড (MCC)। radioType gsm (ডিফল্ট), wcdma , lte এবং nr এর জন্য প্রয়োজনীয় ; cdma এর জন্য ব্যবহৃত হয় না।
বৈধ পরিসর: ০–৯৯৯।
mobileNetworkCode number ( uint32 ) সেল টাওয়ারের মোবাইল নেটওয়ার্ক কোড। এটি GSM, WCDMA, LTE এবং NR এর জন্য MNC।
সিডিএমএ সিস্টেম আইডি (এসআইডি) ব্যবহার করে।		 প্রয়োজন।
বহুজাতিক কোম্পানির জন্য বৈধ পরিসর: ০–৯৯৯।
SID এর জন্য বৈধ পরিসর: 0–32767।

নিম্নলিখিত ঐচ্ছিক ক্ষেত্রগুলি ব্যবহার করা হয় না, তবে মানগুলি উপলব্ধ থাকলে অন্তর্ভুক্ত করা যেতে পারে।

মাঠ JSON টাইপ বিবরণ মন্তব্য
age number ( uint32 ) এই কোষটি প্রাথমিক হওয়ার পর থেকে মিলিসেকেন্ডের সংখ্যা। যদি বয়স 0 হয়, তাহলে cellId অথবা newRadioCellId একটি বর্তমান পরিমাপ উপস্থাপন করে।
signalStrength number ( double ) রেডিও সিগন্যালের শক্তি dBm-এ পরিমাপ করা হয়।
timingAdvance number ( double ) টাইমিং অ্যাডভান্স মান।

cellId গণনা করা হচ্ছে

NR (5G) এর পূর্ববর্তী রেডিও প্রকারগুলি নেটওয়ার্ক সেল আইডি জিওলোকেশন API-তে পাস করার জন্য 32-বিট cellId ক্ষেত্র ব্যবহার করে।

  • GSM (2G) নেটওয়ার্কগুলি ১৬-বিট সেল আইডি (CID) ব্যবহার করে। বৈধ পরিসর: ০–৬৫৫৩৫।
  • CDMA (2G) নেটওয়ার্কগুলি ১৬-বিট বেস স্টেশন আইডি (BID) ব্যবহার করে। বৈধ পরিসর: ০–৬৫৫৩৫।
  • WCDMA (3G) নেটওয়ার্কগুলি UTRAN/GERAN সেল আইডেন্টিটি (UC-ID) ব্যবহার করে, যা একটি 28-বিট পূর্ণসংখ্যার মান যা 12-বিট রেডিও নেটওয়ার্ক কন্ট্রোলার আইডেন্টিফায়ার (RNC-ID) এবং 16-বিট সেল আইডি (CID) কে সংযুক্ত করে।
    সূত্র: rnc_id << 16 | cid .
    বৈধ পরিসর: ০–২৬৮৪৩৫৪৫৫।
    দ্রষ্টব্য: WCDMA নেটওয়ার্কগুলিতে শুধুমাত্র 16-বিট সেল আইডি মান নির্দিষ্ট করলে ভুল বা শূন্য ফলাফল পাওয়া যায়।
  • LTE (4G) নেটওয়ার্কগুলি E-UTRAN সেল আইডেন্টিটি (ECI) ব্যবহার করে, যা একটি 28-বিট পূর্ণসংখ্যার মান যা 20-বিট E-UTRAN নোড B আইডেন্টিফায়ার (eNBId) এবং 8-বিট সেল আইডি (CID) কে সংযুক্ত করে।
    সূত্র: enb_id << 8 | cid .
    বৈধ পরিসর: ০–২৬৮৪৩৫৪৫৫।
    দ্রষ্টব্য: LTE নেটওয়ার্কগুলিতে শুধুমাত্র 8-বিট সেল আইডি মান নির্দিষ্ট করলে ভুল বা শূন্য ফলাফল পাওয়া যায়।

API অনুরোধে এই রেঞ্জের বাইরে মান স্থাপন করলে অনির্ধারিত আচরণ দেখা দিতে পারে। Google-এর বিবেচনার ভিত্তিতে API নম্বরটিকে ছোট করে ফেলতে পারে যাতে এটি নথিভুক্ত পরিসরে ফিট হয়, radioType এ একটি সংশোধন অনুমান করতে পারে, অথবা প্রতিক্রিয়ায় কোনও সূচক ছাড়াই একটি NOT_FOUND ফলাফল ফেরত দিতে পারে।

অনুরোধের অংশ হিসেবে LTE সেল টাওয়ার অবজেক্টের একটি উদাহরণ নিচে দেওয়া হল।

{
  ...

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

পূর্ববর্তী অনুরোধের প্রতিক্রিয়াটি এরকম দেখাচ্ছে:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

newRadioCellId গণনা করা হচ্ছে

নতুন নেটওয়ার্ক, যাদের সেল আইডি ৩২ বিটের বেশি, তারা নেটওয়ার্ক সেল আইডি জিওলোকেশন API-তে পাস করার জন্য ৬৪-বিট newRadioCellId ফিল্ড ব্যবহার করে।

  • NR (5G) নেটওয়ার্কগুলি 36-বিট নিউ রেডিও সেল আইডেন্টিটি (NCI) ব্যবহার করে।
    বৈধ পরিসর: ০–৬৮৭১৯৪৭৬৭৩৫।

অনুরোধের অংশ হিসেবে NR সেল টাওয়ার অবজেক্টের একটি উদাহরণ নিচে দেওয়া হল।

{
  ...

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

পূর্ববর্তী অনুরোধের প্রতিক্রিয়া এইরকম দেখাচ্ছে:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

ওয়াইফাই অ্যাক্সেস পয়েন্ট অবজেক্ট

অনুরোধকারী বডির wifiAccessPoints অ্যারেতে অবশ্যই দুটি বা ততোধিক WiFi অ্যাক্সেস পয়েন্ট অবজেক্ট থাকতে হবে যা শারীরিকভাবে স্বতন্ত্র স্থির অ্যাক্সেস পয়েন্ট ডিভাইসগুলিকে প্রতিনিধিত্ব করে। macAddress ক্ষেত্রটি প্রয়োজন। অন্যান্য সমস্ত ক্ষেত্র ঐচ্ছিক। পরিষেবাটি এমন অ্যাক্সেস পয়েন্টগুলিকে উপেক্ষা করে যা চলাচল করে, যেমন বিমান এবং ট্রেনে।

মাঠ JSON টাইপ বিবরণ মন্তব্য
macAddress string ওয়াইফাই নোডের MAC ঠিকানা। এটিকে সাধারণত BSS, BSSID অথবা MAC ঠিকানা বলা হয়। প্রয়োজনীয়। কোলন-বিভাজিত ( : ) হেক্সাডেসিমেল স্ট্রিং।
API ব্যবহার করে শুধুমাত্র সর্বজনীনভাবে পরিচালিত MAC ঠিকানাগুলি সনাক্ত করা যেতে পারে। অন্যান্য MAC ঠিকানাগুলি নীরবে বাদ দেওয়া হয় এবং এর ফলে API অনুরোধ কার্যকরভাবে খালি হয়ে যেতে পারে। বিস্তারিত জানার জন্য, "অকেজো Wifi অ্যাক্সেস পয়েন্টগুলি বাদ দেওয়া" দেখুন।
signalStrength number ( double ) বর্তমান সংকেত শক্তি dBm-এ পরিমাপ করা হয়। ওয়াইফাই অ্যাক্সেস পয়েন্টের জন্য, dBm মান সাধারণত -35 বা তার কম হয় এবং -128 থেকে -10 dBm পর্যন্ত হয়। বিয়োগ চিহ্নটি অন্তর্ভুক্ত করতে ভুলবেন না।
-১০ dBm-এর বেশি মানের জন্য, API 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
}

পূর্ববর্তী অনুরোধের প্রতিক্রিয়াটি এরকম দেখাচ্ছে:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

নমুনা অনুরোধ

যদি আপনি নমুনা ডেটা সহ জিওলোকেশন 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 ঠিকানাগুলি API-এর জন্য কার্যকর অবস্থান সংকেত নয় এবং নীরবে অনুরোধ থেকে বাদ দেওয়া হয়। আপনি macAddress এর সবচেয়ে গুরুত্বপূর্ণ বাইটের দ্বিতীয় সর্বনিম্ন-গুরুত্বপূর্ণ বিট 0 নিশ্চিত করে এই ধরনের MAC ঠিকানাগুলি সরাতে পারেন, যেমন 02:00:00:00:00:00 -এ 2 দ্বারা প্রতিনিধিত্ব করা 1 বিট। সম্প্রচার MAC ঠিকানা ( FF:FF:FF:FF:FF:FF ) হল একটি MAC ঠিকানার উদাহরণ যা এই ফিল্টার দ্বারা কার্যকরভাবে বাদ দেওয়া হবে।

00:00:5E:00:00:00 এবং 00:00:5E:FF:FF:FF এর মধ্যে MAC ঠিকানাগুলির পরিসর IANA এর জন্য সংরক্ষিত এবং প্রায়শই নেটওয়ার্ক পরিচালনা এবং মাল্টিকাস্ট ফাংশনের জন্য ব্যবহৃত হয় যা লোকেশন সিগন্যাল হিসাবে তাদের ব্যবহারকে বাধা দেয়। আপনার API-তে ইনপুট থেকে এই MAC ঠিকানাগুলিও সরিয়ে ফেলা উচিত।

উদাহরণস্বরূপ, জিওলোকেশনের জন্য ব্যবহারযোগ্য MAC ঠিকানাগুলি macs নামক macAddress স্ট্রিংগুলির একটি অ্যারে থেকে সংগ্রহ করা যেতে পারে:

জাভা 
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")));
পাইথন 
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')]
জাভাস্ক্রিপ্ট 
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 অবশিষ্ট থাকবে। যেহেতু এই তালিকায় 2টিরও কম WiFi MAC ঠিকানা রয়েছে, তাই অনুরোধটি সফল হবে না এবং একটি HTTP 404 ( notFound ) প্রতিক্রিয়া ফিরে আসবে।

ভূ-অবস্থান প্রতিক্রিয়া

একটি সফল ভূ-অবস্থান অনুরোধ একটি অবস্থান এবং ব্যাসার্ধ নির্ধারণ করে একটি JSON-ফর্ম্যাটেড প্রতিক্রিয়া প্রদান করে।

  • location : ব্যবহারকারীর আনুমানিক অক্ষাংশ এবং দ্রাঘিমাংশ স্থানাঙ্ক, ডিগ্রীতে। একটি lat এবং একটি lng সাবফিল্ড রয়েছে।
  • accuracy : আনুমানিক অবস্থানের নির্ভুলতা, মিটারে। এটি প্রদত্ত location চারপাশে একটি বৃত্তের ব্যাসার্ধকে প্রতিনিধিত্ব করে। 
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}