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

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

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

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

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

درخواست بدنه

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

یک نمونه از بدنه درخواست 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 (5G) از فیلد cellId 32 بیتی برای ارسال شناسه سلول شبکه به API موقعیت جغرافیایی استفاده می‌کردند.

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

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

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

• شبکه‌های NR (5G) از هویت سلولی رادیویی جدید (NCI) 36 بیتی به همین شکل استفاده می‌کنند.
  محدوده معتبر: 0–68719476735.

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

{
  ...

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

پاسخ به درخواست قبلی به این شکل است:

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

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

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

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

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

حذف نقاط دسترسی وای‌فای بلااستفاده

حذف اشیاء نقطه دسترسی WiFi با macAddress هایی که به صورت محلی مدیریت می‌شوند، می‌تواند میزان موفقیت فراخوانی‌های Geolocation API که از WiFi به عنوان ورودی استفاده می‌کنند را بهبود بخشد. اگر پس از فیلتر کردن، مشخص شود که فراخوانی Geolocation API موفقیت‌آمیز نخواهد بود، می‌توان از راهکارهایی مانند استفاده از سیگنال‌های موقعیت مکانی قدیمی‌تر یا APهای WiFi با سیگنال‌های ضعیف‌تر استفاده کرد. این رویکرد، مصالحه‌ای بین نیاز برنامه شما به تخمین موقعیت مکانی و الزامات دقت و فراخوانی آن است. تکنیک‌های فیلترینگ زیر نحوه فیلتر کردن ورودی‌ها را نشان می‌دهند، اما راهکارهایی را که ممکن است شما به عنوان مهندس برنامه انتخاب کنید، نشان نمی‌دهند.

آدرس‌های MAC که به صورت محلی مدیریت می‌شوند، سیگنال‌های مکان مفیدی برای API نیستند و به طور بی‌صدا از درخواست‌ها حذف می‌شوند. می‌توانید با اطمینان از اینکه دومین بیت کم‌ارزش‌ترین بایت باارزش‌ترین بایت macAddress برابر با 0 است، چنین آدرس‌های MAC را حذف کنید، مثلاً بیت 1 که توسط 2 در 02:00:00:00:00:00 نشان داده می‌شود. آدرس MAC پخش‌شده ( FF:FF:FF:FF:FF:FF ) نمونه‌ای از آدرس MAC است که به طور مفید توسط این فیلتر حذف می‌شود.

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

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

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 آدرس مک وای‌فای دارد، درخواست موفقیت‌آمیز نخواهد بود و پاسخ HTTP 404 ( notFound ) بازگردانده می‌شود.

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

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

• location : مختصات طول و عرض جغرافیایی تخمینی کاربر، بر حسب درجه. شامل یک فیلد فرعی lat و یک فیلد فرعی lng است.
• accuracy : دقت مکان تخمین زده شده، بر حسب متر. این نشان دهنده شعاع دایره اطراف location داده شده است.

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}