طلبات رصد الموقع الجغرافي
يتم إرسال طلبات رصد الموقع الجغرافي باستخدام POST إلى عنوان URL التالي:
https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY
يجب تحديد مفتاح في طلبك، مضمّنًا كقيمة في معلَمة key
. key
هو مفتاح واجهة برمجة التطبيقات لتطبيقك. يحدّد هذا المفتاح تطبيقك لأغراض إدارة
الحصة. تعرَّف على كيفية الحصول على مفتاح.
نص الطلب
يجب أن يكون نص الطلب بتنسيق JSON. وإذا لم يتم تضمين نص الطلب، سيتم عرض النتائج استنادًا إلى عنوان IP لموقع الطلب. يمكن استخدام الحقول التالية، وجميع الحقول اختيارية، ما لم يُذكر خلاف ذلك:
الحقل | نوع JSON | الوصف | Notes |
---|---|---|---|
homeMobileCountryCode |
number (uint32 ) |
رمز بلد الجوّال (مركز عملائي) للشبكة الرئيسية للجهاز. | متوافق مع 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 |
تحدِّد هذه السياسة ما إذا كان يجب استخدام الموقع الجغرافي حسب عنوان IP إذا كانت إشارات شبكة Wi-Fi وبرج شبكة الجوّال غير متوفّرة أو فارغة أو غير كافية لتقدير الموقع الجغرافي للجهاز. | وتكون الإعدادات التلقائية true . اضبط السمة considerIp على
false لمنع العودة إلى الإصدار السابق. |
cellTowers |
array |
مجموعة من عناصر أبراج الاتصالات. | راجِع قسم كائنات برج الخلايا أدناه. |
wifiAccessPoints |
array |
مصفوفة من عناصر نقطة وصول WiFi. | يمكنك الاطّلاع على قسم عناصر نقطة الوصول إلى شبكة Wi-Fi أدناه. |
في ما يلي مثال لنص طلب واجهة برمجة التطبيقات 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 | الوصف | Notes |
---|---|---|---|
cellId |
number (uint32 ) |
المعرّف الفريد للخلية | مطلوبة لـ radioType gsm (الخيار التلقائي) وcdma
وwcdma وlte ، وتم رفضها في nr .راجِع القسم حساب رقم تعريف الخلية أدناه، والذي يسرد أيضًا نطاقات القيم الصالحة لكل نوع من أنواع الاختيارات اللاسلكية. |
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 ) |
الرمز الخاص بالبلد للجوّال (مركز عملائي) الخاص ببرج الاتصالات. | مطلوبة لـ 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 | الوصف | Notes |
---|---|---|---|
age |
number (uint32 ) |
عدد المللي ثانية منذ أن كانت هذه الخلية أساسية. | إذا كان العمر 0، تمثّل السمة cellId أو newRadioCellId أحد القياسات الحالية. |
signalStrength |
number (double ) |
قوة الإشارة اللاسلكية تُقاس بالديسيبل بالمللي واط. | |
timingAdvance |
number (double ) |
قيمة تقدم التوقيت. |
جارٍ احتساب cellId
تستخدم أنواع اللاسلكي التي تسبق NR (5G) حقل cellId
32 بت لتمرير رقم تعريف شبكة الجوّال إلى واجهة برمجة التطبيقات Geolocation API.
- تستخدم شبكات بروتوكول GSM (2G) معرّف الخلية 16 بت (CID) كما هو. النطاق الصالح: 0–65535.
- تستخدم شبكات CDMA (2G) رقم تعريف المحطة الأساسية بتنسيق 16 بت كما هو. النطاق الصالح: من 0 إلى 65535.
- تستخدم شبكات WCDMA (3G) هوية الخلية UTRAN/GERAN (UC-ID)، وهي قيمة بعدد صحيح 28 بت تربط بين معرّف وحدة التحكّم في الشبكة اللاسلكية 12 بت (RNC-ID) ومعرّف الخلية 16 بت (CID).
الصيغة:rnc_id << 16 | cid
.
النطاق الصالح: من 0 إلى 268435455.
ملاحظة: يؤدي تحديد قيمة معرّف الخلية 16 بت فقط في شبكات WCDMA إلى ظهور نتائج غير صحيحة أو صفرية. - تستخدم شبكات LTE (4G) معرّف الخلية E-UTRAN (ECI)، وهي قيمة بعدد صحيح 28 بت تربط بين معرّف عقدة E-UTRAN 20 بت (eNBId) ومعرّف الخلية (CID) 8 بت.
الصيغة:enb_id << 8 | cid
.
النطاق الصالح: من 0 إلى 268435455.
ملاحظة: يؤدي تحديد قيمة رقم تعريف الخلية المؤلّف من 8 بت فقط في شبكات LTE إلى ظهور نتائج غير صحيحة أو صفرية.
وقد يؤدي وضع قيم خارج هذه النطاقات في طلب البيانات من واجهة برمجة التطبيقات إلى حدوث سلوك غير محدّد. وقد تقتطع واجهة برمجة التطبيقات، وفقًا لتقدير 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) هوية الخلية اللاسلكية الجديدة 36 بت (NCI) كما هي.
النطاق الصالح: 0–68719476735.
يوجد مثال على كائن برج خلية NR أدناه.
{ "cellTowers": [ { "newRadioCellId": 68719476735, "mobileCountryCode": 310, "mobileNetworkCode": 410, "age": 0, "signalStrength": -60, } ] }
عناصر نقطة وصول WiFi
يجب أن تحتوي مصفوفة wifiAccessPoints
لنص الطلب على عنصرَين أو أكثر لنقطة وصول WiFi. حقل macAddress
مطلوب، وجميع
الحقول الأخرى اختيارية.
الحقل | نوع JSON | الوصف | Notes |
---|---|---|---|
macAddress |
string |
عنوان MAC لعقدة شبكة WiFi. وعادةً ما يُسمّى عنوان BSS أو BSSID أو MAC. |
مطلوب.سلسلة سداسية عشرية مفصولة بعلامة النقطتين (: ).
ويمكنك فقط تحديد الموقع الجغرافي لعناوين MAC المُدارة عالميًا عبر واجهة برمجة التطبيقات. ويتم تجاهل عناوين MAC الأخرى بدون تنبيه، وقد يؤدي ذلك إلى أن يصبح طلب البيانات من واجهة برمجة التطبيقات فارغًا فعليًا. لمعرفة التفاصيل، يمكنك الاطّلاع على استبعاد نقاط وصول Wi-Fi غير المفيدة. |
signalStrength |
number (double ) |
قوة الإشارة الحالية تُقاس بالديسيبل بالمللي واط. | بالنسبة إلى نقاط وصول شبكة Wi-Fi، تكون قيم ديسيبل ملي واط عادةً -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 }
نماذج الطلبات
إذا كنت تريد تجربة واجهة برمجة التطبيقات Geolocation 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"
تبدو الاستجابة لعناوين MAC السابقة على النحو التالي:
{ "location": { "lat": 37.4241876, "lng": -122.0917381 }, "accuracy": 32.839 }
إلغاء نقاط وصول Wi-Fi غير المستخدَمة
يمكن أن تؤدي إزالة كائنات نقطة وصول Wi-Fi باستخدام macAddress
المُدارة محليًا
إلى تحسين معدل نجاح طلبات البيانات من واجهة برمجة التطبيقات Geolocation API التي تستخدم WiFi كإدخال.
بعد الفلترة، إذا تبيّن أنّ طلب البيانات من واجهة برمجة التطبيقات للموقع الجغرافي لن ينجح،
يمكن استخدام إجراءات تخفيف مثل استخدام إشارات الموقع الجغرافي القديمة أو نقاط الوصول إلى شبكة Wi-Fi ذات
الإشارات الأضعف. يعمل هذا النهج على الموازنة بين حاجة التطبيق إلى تقدير الموقع الجغرافي ومتطلبات الدقة والتذكر. توضّح أساليب الفلترة التالية كيفية فلترة
المدخلات، ولكن لا تعرض إجراءات التخفيف التي قد تختار تطبيقها، بصفتك
مهندس التطبيقات.
ولا تشكّل عناوين MAC التي تتم إدارتها محليًا إشارات مفيدة للموقع الجغرافي لواجهة برمجة التطبيقات، ويتم حذفها بدون تنبيه من الطلبات. يمكنك إزالة عناوين MAC هذه من خلال التأكّد من أنّ البت الثاني الأقل أهمية في بايت macAddress
هو 0
، على سبيل المثال، 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 هذه من إدخالات واجهة برمجة التطبيقات.
على سبيل المثال، يمكن جمع عناوين 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
في القائمة فقط وبما أنّ هذه القائمة تحتوي
على أقل من عنوانَي MAC لشبكة WiFi، لن يكون الطلب ناجحًا وسيتم عرض استجابة HTTP 404 (notFound
).
استجابات رصد الموقع الجغرافي
يؤدي طلب رصد الموقع الجغرافي الناجح إلى عرض استجابة بتنسيق JSON تحدّد موقعًا جغرافيًا ونطاقًا جغرافيًا.
location
: إحداثيات خط العرض وخط الطول المقدَّرة للمستخدم، بالدرجات تحتوي على حقل فرعي واحدlat
وحقلlng
فرعي واحد.accuracy
: دقة الموقع الجغرافي المقدَّر بالمتر يمثّل ذلك نصف قطر دائرة حولlocation
المحدّد.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }