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

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

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

یک نمونه از بدنه درخواست 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 رد شده است .
به بخش محاسبه cellId در زیر مراجعه کنید، که محدوده مقادیر معتبر برای هر نوع رادیو را نیز فهرست می‌کند.
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 : 0-65535.
محدوده معتبر با nr : 0–16777215.
mobileCountryCode number ( uint32 ) کد کشور موبایل (MCC) دکل سلولی. برای radioType gsm (پیش‌فرض)، wcdma ، lte و nr مورد نیاز است ؛ برای cdma استفاده نمی‌شود.
محدوده معتبر: 0-999.
mobileNetworkCode number ( uint32 ) کد شبکه موبایل دکل‌های مخابراتی. این کد، کد ملی شبکه‌های GSM، WCDMA، LTE و NR است.
CDMA از شناسه سیستم (SID) استفاده می‌کند.		 الزامی است.
محدوده معتبر برای MNC: 0-999.
محدوده معتبر برای SID: 0-32767.

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

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

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

میدان نوع JSON توضیحات یادداشت‌ها
macAddress string آدرس MAC گره WiFi. معمولاً BSS، BSSID یا آدرس MAC نامیده می‌شود. الزامی. رشته هگزادسیمال جدا شده با دونقطه ( : ).
فقط آدرس‌های MAC با مدیریت جهانی را می‌توان با استفاده از API پیدا کرد. سایر آدرس‌های MAC به طور بی‌سروصدا حذف می‌شوند و ممکن است منجر به خالی شدن درخواست API شوند. برای جزئیات بیشتر، به حذف نقاط دسترسی Wifi بی‌فایده مراجعه کنید.
signalStrength number ( double ) قدرت سیگنال فعلی که با واحد dBm اندازه‌گیری می‌شود. برای نقاط دسترسی WiFi، مقادیر dBm معمولاً -35 یا کمتر هستند و از -128 تا -10 dBm متغیر هستند. حتماً علامت منها را نیز در نظر بگیرید.
برای مقادیر بزرگتر از -10 dBm، API مقدار NOT FOUND را برمی‌گرداند.
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
}

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

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