طلب الموقع الجغرافي والرد عليه

طلبات رصد الموقع الجغرافي

يتم إرسال طلبات رصد الموقع الجغرافي باستخدام 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، على سبيل المثال، البت 1 الذي يمثّل 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:

Java
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")));
    
Python
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')]
    
JavaScript
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
}