طلبات رصد الموقع الجغرافي
يتم إرسال طلبات رصد الموقع الجغرافي باستخدام 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 . |
على الرغم من أنّ هذا الحقل اختياري، يجب تضمينه دائمًا إذا كان العميل معروفًا. إذا تم حذف الحقل، يتم ضبط القيمة gsm تلقائيًا في Geolocation API،
ما يؤدّي إلى ظهور نتائج غير صالحة أو عدم ظهور أي نتائج إذا كان نوع الراديو
المفترض غير صحيح. |
carrier |
string |
اسم مشغّل شبكة الجوّال | |
considerIp |
boolean |
يحدد ما إذا كان سيتم رصد الموقع الجغرافي مرة أخرى لعنوان IP في حال كانت إشارات WiFi وبرج الاتصالات مفقودة أو فارغة أو غير كافية لتقدير الموقع الجغرافي للجهاز. | وتكون القيمة التلقائية هي 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 Cell Identity (ECI)، وهي قيمة عددية 28 بت تضم تسلسلاً لمعرِّف العقدة E-UTRAN B 20 بت (eNBId) ومعرِّف الخلية 8 بت (CID).
الصيغة: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 ) |
قوة الإشارة الحالية تقاس بالديسيبل بالملي واط. | بالنسبة إلى نقاط وصول WiFi، تكون قيم ديسيبل ميلي واط عادةً -35 أو أقل وتتراوح بين -128 و-10 ديسيبل ملي واط. تأكد من تضمين علامة الطرح. |
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 }
نماذج الطلبات
إذا أردت تجربة واجهة برمجة التطبيقات Geolocation 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 غير المستخدمة
يمكن أن تؤدي إزالة عناصر نقطة وصول Wi-Fi التي تحتوي على macAddress
والتي
تتم إدارتها محليًا
إلى تحسين معدّل نجاح طلبات البيانات من واجهة برمجة التطبيقات Geolocation API التي تستخدم WiFi كإدخال.
بعد الفلترة، قد يتبيّن أنّ طلب البيانات من واجهة برمجة التطبيقات Geolocation API
لن ينجح في إجراءات التخفيف، مثل استخدام إشارات الموقع الجغرافي القديمة أو نقاط الوصول إلى 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 لشبكة Wi-Fi، لن يتمّ تنفيذ الطلب
وسيتم عرض استجابة HTTP 404
(notFound
).
استجابات رصد الموقع الجغرافي
يعرض طلب رصد الموقع الجغرافي الناجح استجابة بتنسيق JSON تحدِّد الموقع الجغرافي والنطاق الجغرافي.
location
: الإحداثيات المقدّرة لخط العرض وخط الطول للمستخدم بالدرجات تحتوي على حقلlat
واحد وحقلlng
فرعي واحد.accuracy
: دقة الموقع الجغرافي المقدَّر بالمتر يمثّل ذلك نصف قطر الدائرة حولlocation
المحدَّد.
{ "location": { "lat": 37.421875199999995, "lng": -122.0851173 }, "accuracy": 120 }