درخواست و پاسخ موقعیت جغرافیایی

درخواست‌های موقعیت جغرافیایی

درخواست‌های موقعیت جغرافیایی بااستفاده از POST به نشانی وب زیر ارسال می‌شوند:

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

باید کلیدی را در درخواستتان مشخص کنید که به‌عنوان مقدار پارامتر key گنجانده شده باشد. key کلید میانای برنامه‌سازی کاربردی برنامه شما است. این کلید برنامه شما را برای اهداف مدیریت سهمیه شناسایی می‌کند. با نحوه دریافت کلید آشنا شوید.

متن درخواست

متن درخواست باید در قالب JSON باشد. اگر بدنه درخواست گنجانده نشده باشد، نتایج براساس نشانی IP مکان درخواست برگردانده می‌شود. فیلدهای زیر پشتیبانی می‌شوند و همه فیلدها اختیاری هستند، مگراینکه خلاف آن ذکر شده باشد:

فیلد نوع JSON شرح یادداشت‌ها
homeMobileCountryCode ‫number‏ (uint32) کد کشور تلفن همراه (MCC) برای شبکه خانه دستگاه. پشتیبانی‌شده برای radioType gsm (پیش‌فرض)، wcdma، lte، و nr؛ برای cdma استفاده نمی‌شود.
محدوده معتبر: ۰–۹۹۹.
homeMobileNetworkCode ‫number‏ (uint32) کد شبکه تلفن همراه برای شبکه خانگی دستگاه. این MNC برای GSM،‏ WCDMA،‏ LTE، و NR است.
CDMA از «شناسه سیستم» (SID) استفاده می‌کند		 محدوده معتبر برای کد شبکه تلفن همراه: ۰ تا ۹۹۹.
محدوده معتبر برای SID: ‏۰–۳۲۷۶۷.
radioType string نوع رادیو تلفن همراه. مقادیر پشتیبانی‌شده عبارت‌اند از gsm، cdma، wcdma، lte، و nr. اگرچه این فیلد اختیاری است، اگر نوع رادیو برای مشتری شناخته‌شده باشد، باید همیشه گنجانده شود.
اگر فیلد حذف شود، Geolocation API به‌طور پیش‌فرض روی gsm تنظیم می‌شود، که اگر نوع رادیویی فرض‌شده نادرست باشد، منجر به نتایج نامعتبر یا صفر خواهد شد.
carrier string نام شرکت مخابراتی.
considerIp boolean مشخص می‌کند که اگر سیگنال‌های برج سلولی و Wi-Fi وجود نداشته باشد، خالی باشد، یا برای تخمین مکان دستگاه کافی نباشد، آیا به مکان‌یابی جغرافیایی IP برگردد یا نه. پیش‌فرض‌ها به true. considerIp را روی false تنظیم کنید تا از بازگشت به حالت قبلی جلوگیری شود.
cellTowers array آرایه‌ای از اشیای برج سلولی. بخش اشیاء دکل سلولی را در زیر ببینید.
wifiAccessPoints array آرایه‌ای از اشیای نقطه دسترسی Wi-Fi. بخش اشیاء نقطه دسترسی WiFi را در زیر ببینید.

نمونه‌ای از بدنه درخواست Geolocation API در زیر نشان داده شده است.

{
  "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.
بخش محاسبه شناسه سلول را در زیر ببینید که محدوده مقادیر معتبر برای هر نوع رادیو را نیز فهرست می‌کند.
newRadioCellId ‫number‏ (uint64) شناسه یکتای سلول NR (5G). برای radioType nr الزامی است؛ برای انواع دیگر رد شده است.
بخش محاسبه کردن newRadioCellId را در زیر ببینید، که محدوده مقدار معتبر برای این فیلد را نیز فهرست می‌کند.
locationAreaCode ‫number‏ (uint32) کد منطقه مکان (LAC) برای شبکه‌های GSM و WCDMA.
شناسه شبکه (NID) برای شبکه‌های CDMA.
کد منطقه ردیابی (TAC) برای شبکه‌های LTE و NR.		 برای radioType gsm (پیش‌فرض) و cdma الزامی است، برای مقادیر دیگر اختیاری است.
محدوده معتبر با gsm،‏ cdma،‏ wcdma و lte: ۰–۶۵۵۳۵.
محدوده معتبر با nr: ۰–۱۶۷۷۷۲۱۵.
mobileCountryCode ‫number‏ (uint32) کد کشور تلفن همراه (MCC) مربوط به دکل سلولی. موردنیاز برای radioType gsm (پیش‌فرض)، wcdma، lte و nr؛ برای cdma استفاده نمی‌شود.
محدوده معتبر: ۰–۹۹۹.
mobileNetworkCode ‫number‏ (uint32) کد شبکه تلفن همراه دکل سلولی. این MNC برای GSM،‏ WCDMA،‏ LTE، و NR است.
CDMA از «شناسه سیستم» (SID) استفاده می‌کند.		 الزامی.
محدوده معتبر برای کد شبکه تلفن همراه: ۰ تا ۹۹۹.
محدوده معتبر برای SID: ‏۰–۳۲۷۶۷.

فیلدهای اختیاری زیر استفاده نمی‌شوند، اما اگر مقادیر دردسترس باشند، ممکن است گنجانده شوند.

فیلد نوع JSON شرح یادداشت‌ها
age ‫number‏ (uint32) تعداد میلی‌ثانیه‌ها از زمانی که این سلول اصلی بوده است. اگر سن ۰ باشد، cellId یا newRadioCellId نشان‌دهنده اندازه‌گیری فعلی است.
signalStrength ‫number‏ (double) قدرت سیگنال رادیویی که با واحد دسی‌بل میلی‌وات اندازه‌گیری می‌شود.
timingAdvance ‫number‏ (double) مقدار پیش‌افتادگی زمانی.

درحال محاسبه cellId

انواع رادیو قبل‌از NR (نسل پنجم) از فیلد ۳۲ بیتی cellId برای ارسال شناسه سلول شبکه به Geolocation API استفاده می‌کنند.

  • شبکه‌های GSM‏ (2G) از «شناسه سلول» (CID) ۱۶ بیتی همان‌طور که هست استفاده می‌کنند. گستره معتبر: ۰ تا ۶۵۵۳۵.
  • شبکه‌های CDMA‏ (2G) از «شناسه ایستگاه پایه» (BID) ۱۶ بیتی همان‌طور که هست استفاده می‌کنند. محدوده معتبر: ۰–۶۵۵۳۵.
  • شبکه‌های WCDMA (نسل سوم) از «شناسه سلول UTRAN/GERAN»‏ (UC-ID) استفاده می‌کنند که مقدار عدد صحیح ۲۸ بیتی است که «شناسه کنترل‌کننده شبکه رادیویی» (RNC-ID) ۱۲ بیتی و «شناسه سلول» (CID) ۱۶ بیتی را به‌هم متصل می‌کند.
    فرمول: rnc_id << 16 | cid.
    محدوده معتبر: ۰–۲۶۸۴۳۵۴۵۵.
    توجه: مشخص کردن فقط مقدار شناسه سلول ۱۶ بیتی در شبکه‌های WCDMA منجر به نتایج نادرست یا صفر می‌شود.
  • شبکه‌های LTE‏ (4G) از «شناسه سلول E-UTRAN»‏ (ECI) استفاده می‌کنند که مقدار عدد صحیح ۲۸ بیتی است که «شناسه گره B‏ E-UTRAN»‏ (eNBId) بیست بیتی و «شناسه سلول» (CID) هشت بیتی را به‌هم متصل می‌کند.
    فرمول: enb_id << 8 | cid.
    محدوده معتبر: ۰–۲۶۸۴۳۵۴۵۵.
    توجه: مشخص کردن فقط مقدار شناسه سلول ۸ بیتی در شبکه‌های LTE منجر به نتایج نادرست یا صفر می‌شود.

قرار دادن مقادیر خارج از این محدوده‌ها در درخواست API ممکن است منجر به رفتار تعریف‌نشده شود. میانای برنامه‌سازی کاربردی، به‌صلاحدید Google، ممکن است عدد را کوتاه کند تا در محدوده مستندشده قرار گیرد، اصلاحیه‌ای برای 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

شبکه‌های جدیدتر که شناسه سلولی آن‌ها طولانی‌تر از ۳۲ بیت است، از فیلد ۶۴ بیتی newRadioCellId برای ارسال شناسه سلولی شبکه به Geolocation API استفاده می‌کنند.

  • شبکه‌های NR‏ (5G) از «شناسه سلول رادیویی جدید» (NCI) ۳۶ بیتی همان‌طور که هست استفاده می‌کنند.
    محدوده معتبر: ۰ تا ۶۸۷۱۹۴۷۶۷۳۵.

یک نمونه شیء برج سلولی NR که بخشی از بدنه درخواست است در زیر آمده است.

{
  ...

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

پاسخ به درخواست قبلی به‌این‌صورت است:

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

اشیاء نقطه دسترسی WiFi

آرایه wifiAccessPoints بدنه درخواست باید حاوی دو یا چند شیء نقطه دسترسی Wi-Fi باشد که نشان‌دهنده دستگاه‌های نقطه دسترسی ثابت متمایز از لحاظ فیزیکی هستند. فیلد macAddress الزامی است. همه فیلدهای دیگر اختیاری است. این سرویس نقاط دسترسی را که حرکت می‌کنند، مثل نقاط دسترسی موجود در هواپیما و قطار، نادیده می‌گیرد.

فیلد نوع JSON شرح یادداشت‌ها
macAddress string مک آدرس گره Wi-Fi. معمولاً به آن BSS،‏ BSSID، یا نشانی MAC گفته می‌شود. الزامی.رشته شانزده‌شانزدهی جداشده با دونقطه (:).
فقط مک آدرس‌های مدیریت‌شده به‌صورت جهانی را می‌توان بااستفاده از API مکان‌یابی کرد. دیگر نشانی‌های MAC بدون اطلاع حذف می‌شوند و ممکن است باعث شوند درخواست API عملاً خالی شود. برای جزئیات، حذف نقاط دسترسی Wi-Fi بلااستفاده را ببینید.
signalStrength ‫number‏ (double) قدرت سیگنال فعلی که با واحد دسی‌بل میلی‌وات اندازه‌گیری می‌شود. برای نقاط دسترسی Wi-Fi، مقادیر dBm معمولاً ۳۵- یا کمتر است و از ۱۲۸- تا ۱۰- dBm متغیر است. حتماً علامت منفی را وارد کنید.
برای مقادیر بیشتر از -۱۰ دسی‌بل میلی‌وات، میانای برنامه‌سازی کاربردی NOT FOUND را برمی‌گرداند.
age ‫number‏ (uint32) تعداد میلی‌ثانیه‌ها از زمان شناسایی این نقطه دسترسی.
channel ‫number‏ (uint32) کانالی که کلاینت ازطریق آن با نقطه دسترسی ارتباط برقرار می‌کند.
signalToNoiseRatio ‫number‏ (double) نسبت سیگنال به نوفه فعلی اندازه‌گیری‌شده برحسب دسی‌بل.

نمونه‌ای از شیء نقطه دسترسی Wi-Fi که بخشی از بدنه درخواست است، در زیر نشان داده شده است.

{
  ...
  
  "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
}

درخواست‌های نمونه

اگر می‌خواهید 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
}

درحال حذف نقاط دسترسی Wi-Fi استفاده‌نشده

برداشتن اشیای نقطه دسترسی WiFi با macAddressهایی که یا نشانی همه‌فرستی (FF:FF:FF:FF:FF:FF) هستند یا توسط IANA رزرو شده‌اند می‌تواند نرخ موفقیت تماس‌های Geolocation API را که از WiFi به‌عنوان ورودی استفاده می‌کنند بهبود بخشد. اگر پس‌از فیلتر کردن مشخص شود که فراخوانی Geolocation API موفقیت‌آمیز نخواهد بود، می‌توان از اقدامات کاهشی مثل استفاده از سیگنال‌های مکان قدیمی‌تر یا نقاط دسترسی Wi-Fi با سیگنال‌های ضعیف‌تر استفاده کرد. این رویکرد موازنه‌ای است بین نیاز برنامه‌تان به تخمین مکان و الزامات دقت و فراخوانی آن. تکنیک‌های فیلتر کردن زیر نشان می‌دهند که چگونه ورودی‌ها را فیلتر کنید، اما اقدامات کاهشی را که ممکن است شما به‌عنوان مهندس برنامه انتخاب کنید اعمال کنید نشان نمی‌دهند.

محدوده نشانی‌های MAC بین 00:00:5E:00:00:00 و 00:00:5E:FF:FF:FF برای IANA رزرو شده است و اغلب برای مدیریت شبکه و عملکردهای چندپخشی استفاده می‌شود، که مانع استفاده از آن‌ها به‌عنوان سیگنال مکان می‌شود. همچنین باید این نشانی‌های MAC را از ورودی‌های API بردارید.

برای مثال، مک آدرس‌های قابل‌استفاده برای «مکان‌یابی جغرافیایی» را می‌توان از آرایه‌ای از رشته‌های macAddress با نام macs جمع‌آوری کرد:

جاوا
String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
Python
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
جاوا اسکریپت
macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && m.substr(0, 8).toUpperCase() !== '00:00:5E');

بااستفاده از این فیلتر، فقط 1c:34:56:78:9a:bc در فهرست باقی می‌ماند. چون این فهرست کمتر از ۲ مک آدرس Wi-Fi دارد، درخواست موفقیت‌آمیز نخواهد بود و پاسخ HTTP 404 (notFound)برگردانده می‌شود.

پاسخ‌های موقعیت جغرافیایی

درخواست مکان جغرافیایی موفق پاسخی با قالب JSON برمی‌گرداند که مکان و شعاع را تعریف می‌کند.

  • location: مختصات تخمینی طول و عرض جغرافیایی کاربر، به درجه. حاوی یک زیرفیلد lat و یک زیرفیلد lng است.
  • accuracy: دقت مکان تخمینی، به متر. این نشان‌دهنده شعاع دایره‌ای در اطراف location داده‌شده است.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

این میانای برنامه‌سازی کاربردی مکان و شعاع دقت را براساس سیگنال‌های ورودی برمی‌گرداند. اگرچه میانای برنامه‌سازی کاربردی می‌تواند مکان بسیار دقیقی را برگرداند، اما دقت ممکن است بسته به منبع، تعداد، تراکم، و قدرت سیگنال‌های دردسترس متفاوت باشد. معمولاً می‌توانید انتظار شعاع‌های دقت زیر را داشته باشید:

  • نقاط دسترسی Wi-Fi: اگر درخواست شامل دو یا چند wifiAccessPoints باشد، شعاع دقت برگردانده‌شده معمولاً حدود ۲۰ متر است. دقت با تعداد نقاط دسترسی و سیگنال‌های قوی‌تر (اندازه‌گیری‌شده برحسب dBm) بهبود می‌یابد، و قدرت سیگنال معمولاً از ۱۰۰- تا ۲۰- dBm متغیر است.
  • دکل‌های تلفن همراه: اگر اطلاعات Wi-Fi دردسترس نباشد یا کافی نباشد، ‫API از cellTowers برای مکان استفاده می‌کند. دقت به‌طور قابل‌توجهی با نوع دکل سلولی، قدرت سیگنال، و تراکم شبکه متفاوت است:
    • سلول‌های ماکرو (رایج‌ترین نوع، که برای پوشش منطقه وسیع استفاده می‌شود) دقت کمتری ارائه می‌دهند. شعاع معمولاً در محدوده صدها متر است و در مناطقی که پوشش برج سلولی پراکنده است، می‌تواند تا چند هزار متر باشد. برای سلول‌های ماکرو، دستیابی به شعاع دقت کمتر از ۱۰۰ متر غیرمعمول است. دقت معمولاً برای دکل‌های سلولی با سیگنال‌های قوی بیشتر است. سیگنال‌های قوی معمولاً برای LTE بیشتر از ۱۱۰- دسی‌بل میلی‌وات (محدوده سیگنال ۱۴۰- تا ۵۵- دسی‌بل میلی‌وات)، برای WCDMA بیشتر از ۱۰۰- دسی‌بل میلی‌وات (محدوده سیگنال ۱۱۱- تا ۵۳- دسی‌بل میلی‌وات)، برای CDMA بیشتر از ۱۰۰- دسی‌بل میلی‌وات (محدوده سیگنال ۱۲۰- تا ۴۰- دسی‌بل میلی‌وات)، و برای GSM بیشتر از ۸۰- دسی‌بل میلی‌وات (محدوده سیگنال ۱۲۱- تا ۱- دسی‌بل میلی‌وات) است.
    • سلول‌های کوچک (مثلاً، فمتوسل‌ها، پیکوسل‌ها، یا تکرارکننده‌های داخلی) دقیق‌ترین مکان مبتنی بر سلول را با شعاع دقتی در محدوده ۱۰ تا ۳۰ متر ارائه می‌دهند.
  • موقعیت جغرافیایی IP: اگر considerIp برابر با true باشد و هیچ سیگنال Wi-Fi یا دکل سلولی قابل موقعیت‌یابی جغرافیایی نباشد، میانای برنامه‌سازی کاربردی مکان را براساس نشانی IP درخواست تخمین می‌زند. این روش کمترین دقت را دارد و شعاع آن می‌تواند هزاران متر باشد. به چرا شعاع دقت بسیار بزرگ است؟ مراجعه کنید. در راهنمای «عیب‌یابی» ببینید.