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

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

يتم إرسال طلبات الموقع الجغرافي باستخدام طريقة POST إلى عنوان URL التالي:

https://www.googleapis.com/geolocation/v1/geolocate?key=YOUR_API_KEY

يجب تحديد مفتاح في طلبك، ويتم تضمينه كقيمة للمَعلمة key. A key هو مفتاح واجهة برمجة التطبيقات لتطبيقك. يساعد هذا المفتاح في التعرّف على تطبيقك لأغراض إدارة الحصص. تعرف على كيفية الحصول على مفتاح.

نص الطلب

يجب تنسيق نص الطلب بتنسيق JSON. إذا لم يتم تضمين نص الطلب، يتم عرض النتائج استنادًا إلى عنوان IP لموقع الطلب. الحقول التالية متاحة، وكلها اختيارية ما لم يُنص على خلاف ذلك:

نعرض أدناه مثالاً على نص طلب بيانات من واجهة برمجة التطبيقات Geolocation API.

{
  "homeMobileCountryCode": 310,
  "homeMobileNetworkCode": 410,
  "radioType": "lte",
  "carrier": "Vodafone",
  "considerIp": true,
  "cellTowers": [
    // See the Cell Tower Objects section below.
  ],
  "wifiAccessPoints": [
    // See the WiFi Access Point Objects section below.
  ]
}

عناصر أبراج الاتصالات

تحتوي مصفوفة cellTowers في نص الطلب على صفر أو أكثر من عناصر أبراج الاتصالات.

الحقول الاختيارية التالية غير مستخدَمة، ولكن يمكن تضمينها إذا كانت القيم متاحة.

حساب cellId

تستخدم أنواع أجهزة الإرسال والاستقبال قبل شبكة الجيل الخامس (NR) حقل cellId الذي يبلغ 32 بت لتمرير رقم تعريف خلية الشبكة إلى واجهة برمجة التطبيقات Geolocation API.

• تستخدم شبكات GSM (الجيل الثاني) رقم تعريف الخلية (CID) الذي يبلغ 16 بت كما هو. النطاق الصحيح: 0–65535
• تستخدم شبكات CDMA (الجيل الثاني) رقم تعريف المحطة الأساسية (BID) الذي يبلغ 16 بت كما هو. النطاق الصحيح: 0–65535
• تستخدم شبكات WCDMA (الجيل الثالث) رقم تعريف خلية UTRAN/GERAN (UC-ID)، وهو قيمة عدد صحيح تبلغ 28 بت تجمع بين رقم تعريف وحدة التحكّم في شبكة الإرسال والاستقبال اللاسلكية (RNC-ID) الذي يبلغ 12 بت ورقم تعريف الخلية (CID) الذي يبلغ 16 بت .
  الصيغة: rnc_id << 16 | cid.
  النطاق الصحيح: 0–268435455
  ملاحظة: يؤدي تحديد قيمة رقم تعريف الخلية الذي يبلغ 16 بت فقط في شبكات WCDMA إلى ظهور نتائج غير صحيحة أو صفرية.
• تستخدم شبكات LTE (الجيل الرابع) رقم تعريف خلية E-UTRAN (ECI)، وهو قيمة عدد صحيح تبلغ 28 بت تجمع بين رقم تعريف العقدة B في E-UTRAN (eNBId) الذي يبلغ 20 بت ورقم تعريف الخلية (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
    }
  ]
}

تظهر الاستجابة للطلب السابق على النحو التالي:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

حساب newRadioCellId

تستخدم الشبكات الأحدث، التي تكون أرقام تعريف خلاياها أطول من 32 بت، حقل newRadioCellId الذي يبلغ 64 بت لتمرير رقم تعريف خلية الشبكة إلى واجهة برمجة التطبيقات Geolocation API.

• تستخدم شبكات NR (الجيل الخامس) رقم تعريف خلية New Radio (NCI) الذي يبلغ 36 بت كما هو.
  النطاق الصحيح: 0–68719476735

نعرض أدناه مثالاً على عنصر برج اتصالات NR، وهو جزء من نص الطلب.

{
  ...

  "cellTowers": [
    {
      "newRadioCellId": 68719476735,
      "mobileCountryCode": 310,
      "mobileNetworkCode": 410,
      "age": 0,
      "signalStrength": -60,
    }
  ]
}

تظهر الاستجابة للطلب السابق على النحو التالي:

{
  "location": {
    "lat": 37.7646157,
    "lng": -122.4127361
  },
  "accuracy": 1458.5570522410717
}

عناصر نقاط وصول Wi-Fi

يجب أن تحتوي مصفوفة wifiAccessPoints في نص الطلب على عنصرَين أو أكثر من عناصر نقاط وصول Wi-Fi التي تمثّل أجهزة نقاط وصول ثابتة مختلفة فعليًا. الحقل macAddress مطلوب. جميع الحقول الأخرى اختيارية. تتجاهل الخدمة نقاط الوصول المتحركة، مثل تلك الموجودة في الطائرات والقطارات.

نعرض أدناه مثالاً على عنصر نقطة وصول Wi-Fi، وهو جزء من نص الطلب، ويتم عرضه أدناه.

{
  ...
  
  "macAddress": "f0:d5:bf:fd:12:ae",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

تظهر الاستجابة للطلب السابق على النحو التالي:

{
  "location": {
    "lat": 37.7801129,
    "lng": -122.4168229
  },
  "accuracy": 180.052
}

أمثلة على الطلبات

إذا أردت تجربة واجهة برمجة التطبيقات 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
}

حذف نقاط وصول Wi-Fi غير المستخدَمة

يمكن أن يؤدي إزالة عناصر نقاط وصول Wi-Fi التي تكون macAddress إما عنوان بث (FF:FF:FF:FF:FF:FF) أو محجوزًا من قِبل IANA إلى تحسين معدّل نجاح طلبات واجهة برمجة التطبيقات Geolocation API التي تستخدم شبكة Wi-Fi كإدخال. إذا تبيّن بعد الفلترة أنّ طلب بيانات من واجهة برمجة التطبيقات Geolocation API لن ينجح، يمكن استخدام إجراءات تخفيفية، مثل استخدام إشارات الموقع الجغرافي الأقدم أو نقاط وصول Wi-Fi ذات الإشارات الأضعف. يمثّل هذا النهج حلاً وسطًا بين حاجة تطبيقك إلى تقدير الموقع الجغرافي ومتطلباته من حيث الدقة والاستدعاء. توضّح تقنيات الفلترة التالية كيفية فلترة الإدخالات، ولكنها لا تعرض إجراءات التخفيف التي قد تختار تطبيقها بصفتك مهندس التطبيق.

نطاق عناوين MAC بين 00:00:5E:00:00:00 و 00:00:5E:FF:FF:FF محجوز لـ IANA ويُستخدم غالبًا لإدارة الشبكة ووظائف البث المتعدد، ما يمنع استخدامه كإشارة موقع جغرافي. يجب أيضًا إزالة عناوين MAC هذه من الإدخالات إلى واجهة برمجة التطبيقات.

على سبيل المثال، يمكن جمع عناوين MAC القابلة للاستخدام في Geolocation من مصفوفة من سلاسل macAddress باسم macs:

String[] macs = {"ff:ff:ff:ff:ff:ff", "1c:34:56:78:9a:bc", "00:00:5e:00:00:01"};
ArrayList<String> _macs = new ArrayList<>(Arrays.asList(macs));
_macs.removeIf(m -> !(!m.toUpperCase().equals("FF:FF:FF:FF:FF:FF")
                      && !m.substring(0, 8).toUpperCase().equals("00:00:5E")));
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01']
macs = [m for m in macs if (m.upper() != "FF:FF:FF:FF:FF:FF" and m[:8].upper() != '00:00:5E')]
    

macs = ['ff:ff:ff:ff:ff:ff', '1c:34:56:78:9a:bc', '00:00:5e:00:00:01'];
macs = macs.filter(m => m.toUpperCase() !== "FF:FF:FF:FF:FF:FF"
                        && 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
}

تعرض واجهة برمجة التطبيقات موقعًا جغرافيًا ونصف قطر الدقة استنادًا إلى الإشارات المُدخَلة. على الرغم من أنّ واجهة برمجة التطبيقات يمكنها عرض موقع جغرافي دقيق للغاية، قد تختلف الدقة استنادًا إلى مصدر الإشارات وعددها وكثافتها وقوتها المتاحة. يمكنك عادةً توقّع أنصاف الأقطار التالية للدقة:

• نقاط وصول Wi-Fi: إذا كان الطلب يتضمّن عنصرَين أو أكثر من wifiAccessPoints، يكون نصف قطر الدقة المعروض عادةً حوالي 20 مترًا. تتحسّن الدقة مع زيادة عدد نقاط الوصول و الإشارات الأقوى (مقاسة بالديسيبل ميللي واط)، وتتراوح قوة الإشارة عادةً بين ‎-100 و‎-20 ديسيبل ميللي واط.
• أبراج الاتصالات: إذا كانت معلومات شبكة Wi-Fi غير متاحة أو غير كافية، تستخدم واجهة برمجة التطبيقات cellTowers لتحديد الموقع الجغرافي. تختلف الدقة بشكلٍ كبير حسب نوع برج الاتصالات وقوة الإشارة وكثافة الشبكة:
  • الخلايا الكبيرة (النوع الأكثر شيوعًا، والمستخدَم لتغطية مساحة واسعة ) توفّر دقة أقل. يتراوح نصف القطر عادةً بين مئات الأمتار ، ويمكن أن يصل إلى عدة آلاف من الأمتار في المناطق التي تكون فيها تغطية أبراج الاتصالات قليلة. بالنسبة إلى الخلايا الكبيرة، من غير الشائع تحقيق نصف قطر دقة أقل من 100 متر. تكون الدقة أعلى بشكلٍ عام لأبراج الاتصالات ذات الإشارات القوية. تكون الإشارات القوية عادةً أكبر من ‎-110 ديسيبل ميللي واط لشبكة LTE (نطاق الإشارة من ‎-140 إلى ‎-55 ديسيبل ميللي واط)، وأكبر من ‎-100 ديسيبل ميللي واط لشبكة WCDMA (نطاق الإشارة من ‎-111 إلى ‎-53 ديسيبل ميللي واط)، وأكبر من ‎-100 ديسيبل ميللي واط لشبكة CDMA (نطاق الإشارة من ‎-120 إلى ‎-40 ديسيبل ميللي واط)، وأكبر من ‎-80 ديسيبل ميللي واط لشبكة GSM (نطاق الإشارة من ‎-121 إلى ‎-1 ديسيبل ميللي واط).
  • توفر الخلايا الصغيرة (مثل خلايا Femtocell أو Picocell أو أجهزة إعادة الإرسال الداخلية توفر الموقع الجغرافي الأكثر دقة استنادًا إلى الخلية، مع أنصاف أقطار دقة يمكن أن تتراوح بين 10 و30 مترًا.
• تحديد الموقع الجغرافي استنادًا إلى عنوان IP: إذا كانت قيمة considerIp هي true ولم يكن من الممكن تحديد الموقع الجغرافي لإشارات شبكة Wi-Fi أو أبراج الاتصالات، تقدّر واجهة برمجة التطبيقات الموقع الجغرافي استنادًا إلى عنوان IP للطلب. توفر هذه الطريقة الـ أقل دقة، مع أنصاف أقطار يمكن أن تصل إلى آلاف الأمتار. يُرجى الاطّلاع على لماذا يكون نصف قطر الدقة كبيرًا جدًا؟ في دليل تحديد المشاكل وحلّها.