این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

بررسی اجمالی

مقدمه

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": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "94:b4:0f:fd:c1:40",
      "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"

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

{
  "location": {
      "lat": 37.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

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

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

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

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

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

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