مقدمه
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
شما نمی توانند موقعیت جغرافیایی داشته باشند.