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

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

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

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

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

متن درخواست

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

نمونه‌ای از بدنه درخواست 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 بدنه درخواست حاوی صفر یا چند شیء برج سلولی است.

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

درحال محاسبه 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 الزامی است. همه فیلدهای دیگر اختیاری است. این سرویس نقاط دسترسی را که حرکت می‌کنند، مثل نقاط دسترسی موجود در هواپیما و قطار، نادیده می‌گیرد.

نمونه‌ای از شیء نقطه دسترسی 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")));
    

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 درخواست تخمین می‌زند. این روش کمترین دقت را دارد و شعاع آن می‌تواند هزاران متر باشد. به چرا شعاع دقت بسیار بزرگ است؟ مراجعه کنید. در راهنمای «عیب‌یابی» ببینید.