بررسی اجمالی

با مجموعه‌ها، منظم بمانید ذخیره و دسته‌بندی محتوا براساس اولویت‌های شما.

مقدمه

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

ارتباط از طریق HTTPS با استفاده از POST انجام می شود. هر دو درخواست و پاسخ به صورت JSON فرمت شده اند و نوع محتوای هر دو application/json است.

قبل از اینکه شروع کنی

قبل از شروع توسعه با Geolocation API، الزامات احراز هویت (شما به یک کلید API نیاز دارید) و استفاده از API و اطلاعات صورتحساب (شما باید صورتحساب پروژه خود را فعال کنید) را بررسی کنید.

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

درخواست‌های موقعیت جغرافیایی با استفاده از 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 برای غیرفعال کردن fall back 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 مورد نیاز radioType ، برای مقادیر دیگر اختیاری است.
محدوده معتبر با gsm ، cdma ، wcdma و lte: lte .
محدوده معتبر با شماره: nr .
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 نامیده می شود. ضروری. : (دونقطه) رشته هگزادسیمال جدا شده.
signalStrength number ( double ) قدرت سیگنال فعلی بر حسب dBm اندازه گیری می شود. برای نقاط دسترسی WiFi، مقادیر dBm معمولاً 35- یا کمتر است و از 128- تا 10- دسی بل متغیر است. حتما علامت منفی را وارد کنید.
age number ( uint32 ) تعداد میلی ثانیه از زمانی که این نقطه دسترسی شناسایی شده است.
channel number ( uint32 ) کانالی که مشتری از طریق آن با نقطه دسترسی در ارتباط است.
signalToNoiseRatio number ( double ) نسبت سیگنال فعلی به نویز بر حسب دسی بل اندازه گیری می شود.

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

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

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

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

  • location : طول و عرض جغرافیایی تخمینی کاربر، بر حسب درجه. شامل یک زیر فیلد lat و یک lng است.
  • accuracy : دقت مکان تخمین زده شده بر حسب متر. این نشان دهنده شعاع یک دایره در اطراف location داده شده است.
{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

خطاها

در صورت بروز خطا، بدنه پاسخ خطای قالب استاندارد برگردانده می شود و کد وضعیت HTTP روی وضعیت خطا تنظیم می شود.

پاسخ شامل یک شی با یک شی error با کلیدهای زیر است:

  • code : این همان وضعیت HTTP پاسخ است.
  • message : توضیح کوتاهی از خطا.
  • errors : لیستی از خطاهایی که رخ داده است. هر خطا شامل یک شناسه برای نوع خطا ( reason ) و یک توضیح کوتاه ( message ) است.

برای مثال، ارسال JSON نامعتبر، خطای زیر را برمی‌گرداند:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

خطاهای احتمالی عبارتند از:

دلیل دامنه کد وضعیت HTTP شرح
dailyLimitExceeded usageLimits 403 شما از حد مجاز روزانه خود فراتر رفته اید.
keyInvalid usageLimits 400 کلید API شما برای API مکان جغرافیایی معتبر نیست. لطفاً مطمئن شوید که کل کلید را درج کرده‌اید، و یا API را خریداری کرده‌اید یا صورت‌حساب را فعال کرده‌اید و API را فعال کرده‌اید تا سهمیه را بدون هزینه دریافت کنید.
userRateLimitExceeded usageLimits 403 شما از حد درخواستی که در Google Cloud Console پیکربندی کرده اید فراتر رفته اید. این محدودیت معمولاً به صورت درخواست در روز، درخواست در هر 100 ثانیه و درخواست در هر 100 ثانیه برای هر کاربر تنظیم می شود. این محدودیت باید به گونه‌ای پیکربندی شود که از تمام کردن سهمیه روزانه توسط یک گروه یا گروه کوچک از کاربران جلوگیری شود و در عین حال امکان دسترسی معقول به همه کاربران را فراهم کند. برای پیکربندی این محدودیت‌ها به Capping API Usage مراجعه کنید.
notFound geolocation 404 درخواست معتبر بود، اما هیچ نتیجه ای برگردانده نشد.
parseError global 400 بدنه درخواست JSON معتبر نیست. برای جزئیات هر فیلد به بخش درخواست بدنه مراجعه کنید.

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

اگر می‌خواهید API جغرافیایی را با داده‌های نمونه امتحان کنید، JSON زیر را در یک فایل ذخیره کنید:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "84:d4:7e:f6:99:64",
      "signalStrength": -54,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f6:99:71",
      "signalStrength": -43,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "84:d4:7e:f7:21:35",
      "signalStrength": -32,
      "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"

پاسخ برای آدرس‌های مک بالا به این صورت است:

{
  "location": {
      "lat": 37.4237423,
      "lng": -122.0915814
  },
  "accuracy": 20
}

(اگر کلید API ندارید، به دریافت کلید API مراجعه کنید.)

برای آزمایش‌های بیشتر، می‌توانید از دستگاه Android خود با استفاده از Places SDK برای Android و APIهای مکان Android و از دستگاه iOS خود با استفاده از Places SDK برای iOS اطلاعات جمع‌آوری کنید.

سوالات متداول

چرا شعاع accuracy بسیار زیادی در پاسخ موقعیت جغرافیایی خود دریافت می کنم؟

اگر پاسخ موقعیت جغرافیایی شما مقدار بسیار بالایی را در قسمت accuracy نشان می‌دهد، ممکن است سرویس به جای نقاط WiFi یا برج‌های سلولی، بر اساس IP درخواست، موقعیت جغرافیایی را انجام دهد. این ممکن است در صورتی اتفاق بیفتد که هیچ دکل یا نقطه دسترسی معتبر یا شناسایی نشده باشد.

برای تأیید اینکه این مشکل وجود دارد، در درخواست خود، considerIp را روی false قرار دهید. اگر پاسخ 404 باشد، تأیید کرده اید که اشیاء wifiAccessPoints و cellTowers شما نمی توانند موقعیت جغرافیایی داشته باشند.