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

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

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

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

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

درخواست بدن

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

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

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

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

محاسبه cellId

انواع رادیویی قبل از NR (5G) از فیلد cellId 32 بیتی برای ارسال شناسه سلول شبکه به Geolocation API استفاده می کنند.

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

قرار دادن مقادیر خارج از این محدوده ها در درخواست API ممکن است منجر به رفتار نامشخص شود. API، بنا به صلاحدید Google، ممکن است عدد را کوتاه کند تا در محدوده مستند قرار گیرد، یک تصحیح در radioType استنتاج کند، یا یک نتیجه NOT_FOUND را بدون هیچ نشانگری در پاسخ بازگرداند.

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

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

محاسبه newRadioCellId

شبکه های جدیدتر که شناسه سلول آنها بیشتر از 32 بیت است از فیلد newRadioCellId 64 بیتی برای ارسال شناسه سلول شبکه به Geolocation API استفاده می کنند.

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

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

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

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

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

نمونه ای از شی نقطه دسترسی WiFi در زیر نشان داده شده است.

{
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

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

اگر می‌خواهید 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 e که به صورت محلی مدیریت می‌شوند، می‌تواند میزان موفقیت تماس‌های Geolocation API را که از WiFi به عنوان ورودی استفاده می‌کنند، بهبود بخشد. اگر پس از فیلتر کردن، بتوان تشخیص داد که تماس API جغرافیایی موفق نخواهد بود، می‌توان از اقدامات کاهشی مانند استفاده از سیگنال‌های مکان قدیمی‌تر یا APهای WiFi با سیگنال‌های ضعیف‌تر استفاده کرد. این رویکرد یک موازنه بین نیاز برنامه شما به تخمین مکان و دقت و الزامات فراخوانی آن است. تکنیک‌های فیلتر زیر نحوه فیلتر کردن ورودی‌ها را نشان می‌دهند، اما کاهش‌هایی را که ممکن است به‌عنوان مهندس برنامه، انتخاب کنید، نشان نمی‌دهند.

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

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

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

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

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

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