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

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

درخواست‌های موقعیت جغرافیایی با استفاده از 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": "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 رد شد .
بخش 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
    }
  ]
}

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

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

محاسبه newRadioCellId

شبکه های جدیدتر که شناسه سلول آنها بیشتر از 32 بیت است از فیلد newRadioCellId 64 بیتی برای ارسال شناسه سلول شبکه به 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- دسی بل متغیر است. حتما علامت منفی را وارد کنید.
برای مقادیر بیشتر از -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 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
}
 ،

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

درخواست‌های موقعیت جغرافیایی با استفاده از 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": "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 رد شد .
بخش 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
    }
  ]
}

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

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

محاسبه newRadioCellId

شبکه های جدیدتر که شناسه سلول آنها بیشتر از 32 بیت است از فیلد newRadioCellId 64 بیتی برای ارسال شناسه سلول شبکه به 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- دسی بل متغیر است. حتما علامت منفی را وارد کنید.
برای مقادیر بیشتر از -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 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
}
 ،

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

درخواست‌های موقعیت جغرافیایی با استفاده از 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": "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 رد شد .
بخش 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
    }
  ]
}

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

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

محاسبه newRadioCellId

شبکه های جدیدتر که شناسه سلول آنها بیشتر از 32 بیت است از فیلد newRadioCellId 64 بیتی برای ارسال شناسه سلول شبکه به 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- دسی بل متغیر است. حتما علامت منفی را وارد کنید.
برای مقادیر بیشتر از -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 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
}
 ،

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

درخواست‌های موقعیت جغرافیایی با استفاده از 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": "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 رد شد .
بخش 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
    }
  ]
}

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

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

محاسبه newRadioCellId

Newer networks, whose cell IDs are longer than 32 bits use the 64-bit newRadioCellId field for passing the network cell ID to Geolocation API.

  • NR (5G) networks use the 36-bit New Radio Cell Identity (NCI) as is.
    Valid range: 0–68719476735.

An example NR cell tower object, which is part of the request body , is below.

{
  ...

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

The response to the preceding request looks like this:

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

WiFi access point objects

The request body's wifiAccessPoints array must contain two or more WiFi access point objects representing physically distinct stationary access point devices. The macAddress field is required. تمام فیلدهای دیگر اختیاری هستند. The service ignores access points that move, such as those in airplanes and trains.

میدان JSON type توضیحات یادداشت ها
macAddress string The MAC address of the WiFi node. It's typically called a BSS, BSSID or MAC address. مورد نیاز. Colon-separated ( : ) hexadecimal string.
Only universally-administered MAC addresses can be located using the API. Other MAC addresses are silently dropped and may lead to an API request becoming effectively empty. For details, see Dropping useless Wifi access points .
signalStrength number ( double ) The current signal strength measured in dBm. For WiFi access points, dBm values are typically -35 or lower and range from -128 to -10 dBm. Be sure to include the minus sign.
For values greater than -10 dBm, the API returns NOT FOUND .
age number ( uint32 ) The number of milliseconds since this access point was detected.
channel number ( uint32 ) The channel over which the client is communicating with the access point.
signalToNoiseRatio number ( double ) The current signal to noise ratio measured in dB.

An example WiFi access point object, which is part of the request body , is shown below.

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

The response for the preceding request looks like this:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

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

If you'd like to try the Geolocation API with sample data, save the following JSON to a file:

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

You can then use curl to make your request from the command line: 

$ curl -d @your_filename.json -H "Content-Type: application/json" -i "https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY"

The response for the preceding MAC addresses looks like this: 

{
  "location": {
    "lat": 37.4241173,
    "lng": -122.0915717
  },
  "accuracy": 20
}

Dropping unused WiFi access points

Removing WiFi access point objects with macAddress es that are locally-administered can improve the success rate of Geolocation API calls that use WiFi as input. If, after filtering, it can be determined that a Geolocation API call wouldn't succeed, mitigations such as using older location signals or WiFi APs with weaker signals can be used. This approach is a tradeoff between your application's need for a location estimate and its precision and recall requirements. The following filtering techniques demonstrate how to filter the inputs, but don't show the mitigations that you may, as the application engineer, choose to apply.

Locally administered MAC addresses are not useful location signals for the API and are silently dropped from requests. You can remove such MAC addresses by ensuring that the second least-significant bit of the macAddress 's most-significant byte is 0 , eg the 1 bit represented by the 2 in 02:00:00:00:00:00 . The broadcast MAC address ( FF:FF:FF:FF:FF:FF ) is an example of a MAC address that would be usefully excluded by this filter.

The range of MAC addresses between 00:00:5E:00:00:00 and 00:00:5E:FF:FF:FF are reserved for IANA and often used for network management and multicast functions which precludes their use as a location signal. You should also remove these MAC addresses from inputs to the API.

For example, usable MAC addresses for Geolocation can be gathered from an array of macAddress strings named 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');

Using this filter results in only 1c:34:56:78:9a:bc remaining in the list. Because this list has fewer than 2 WiFi MAC addresses , the request wouldn't be successful and an HTTP 404 ( notFound ) response would be returned.

Geolocation responses

A successful geolocation request returns a JSON-formatted response defining a location and radius.

  • location : The user's estimated latitude and longitude coordinates, in degrees. Contains one lat and one lng subfield.
  • accuracy : The accuracy of the estimated location, in meters. This represents the radius of a circle around the given location . 
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}