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

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

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

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 استفاده نمیشه
محدوده معتبر: 0–999.
homeMobileNetworkCode number ( uint32 ) کد شبکه تلفن همراه برای شبکه خانگی دستگاه. این MNC برای GSM، WCDMA، LTE و NR است.
CDMA از شناسه سیستم (SID) استفاده می کند		 محدوده معتبر برای MNC: 0-999.
محدوده معتبر برای SID: 0–32767.
radioType string نوع رادیو سیار مقادیر پشتیبانی شده عبارتند از gsm , cdma , wcdma , lte و nr . در حالی که این فیلد اختیاری است، اما اگر نوع رادیو توسط مشتری شناخته شده باشد، باید همیشه در آن گنجانده شود.
اگر این فیلد حذف شود، Geolocation API به‌طور پیش‌فرض روی gsm است، که اگر نوع رادیویی فرضی نادرست باشد، نتایج نامعتبر یا صفر خواهد بود.
carrier string نام حامل
considerIp boolean مشخص می‌کند که اگر سیگنال‌های WiFi و برج سلولی از دست رفته، خالی یا برای تخمین مکان دستگاه کافی نیستند، به موقعیت جغرافیایی IP برگردند. پیش فرض ها به true برای جلوگیری از عقب افتادن، considerIp را روی false قرار دهید.
cellTowers array مجموعه ای از اشیاء برج سلولی. بخش اشیاء برج سلولی را در زیر ببینید.
wifiAccessPoints array آرایه ای از اشیاء نقطه دسترسی WiFi. بخش اشیاء نقطه دسترسی WiFi را در زیر ببینید.

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

میدان نوع JSON توضیحات یادداشت ها
cellId number ( uint32 ) شناسه منحصر به فرد سلول مورد نیاز برای radioType gsm (پیش‌فرض)، cdma ، wcdma و lte ؛ برای nr رد شد .
بخش Calculating cellId را در زیر ببینید، که همچنین محدوده مقادیر معتبر را برای هر نوع رادیو فهرست می کند.
newRadioCellId number ( uint64 ) شناسه منحصر به فرد سلول NR (5G). مورد نیاز برای radioType nr ; برای انواع دیگر رد شده است .
بخش Calculating newRadioCellId را در زیر ببینید، که محدوده مقادیر معتبر فیلد را نیز فهرست می‌کند.
locationAreaCode number ( uint32 ) کد منطقه ای مکان (LAC) برای شبکه های GSM و WCDMA.
شناسه شبکه (NID) برای شبکه های CDMA.
کد منطقه ردیابی (TAC) برای شبکه های LTE و NR.		 برای radioType gsm (پیش‌فرض) و cdma مورد نیاز است ، برای مقادیر دیگر اختیاری است.
محدوده معتبر با gsm ، cdma ، wcdma و lte : 0–65535.
محدوده معتبر با nr : 0–16777215.
mobileCountryCode number ( uint32 ) کد کشور سیار برج تلفن همراه (MCC). مورد نیاز برای radioType gsm (پیش‌فرض)، wcdma ، lte و nr . برای cdma استفاده نمیشه
محدوده معتبر: 0–999.
mobileNetworkCode number ( uint32 ) کد شبکه تلفن همراه برج تلفن همراه. این MNC برای GSM، WCDMA، LTE و NR است.
CDMA از شناسه سیستم (SID) استفاده می کند.		 مورد نیاز.
محدوده معتبر برای MNC: 0-999.
محدوده معتبر برای SID: 0–32767.

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

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

محاسبه 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 مورد نیاز است. تمام فیلدهای دیگر اختیاری هستند.

میدان نوع JSON توضیحات یادداشت ها
macAddress string آدرس MAC گره WiFi. معمولاً آدرس BSS، BSSID یا MAC نامیده می شود. مورد نیاز. رشته هگزادسیمال جدا شده با کولون ( : ).
فقط آدرس های MAC با مدیریت جهانی را می توان از طریق API قرار داد. سایر آدرس‌های MAC بی‌صدا حذف می‌شوند و ممکن است منجر به خالی شدن یک درخواست API شوند. برای جزئیات، رها کردن نقاط دسترسی بی فایده Wifi را ببینید.
signalStrength number ( double ) قدرت سیگنال فعلی بر حسب dBm اندازه گیری می شود. برای نقاط دسترسی WiFi، مقادیر dBm معمولاً 35- یا کمتر است و از 128- تا 10- دسی بل متغیر است. حتما علامت منفی را وارد کنید.
age number ( uint32 ) تعداد میلی ثانیه از زمانی که این نقطه دسترسی شناسایی شده است.
channel number ( uint32 ) کانالی که مشتری از طریق آن با نقطه دسترسی در ارتباط است.
signalToNoiseRatio number ( double ) نسبت سیگنال فعلی به نویز بر حسب دسی بل اندازه گیری می شود.

نمونه ای از شی نقطه دسترسی 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
}