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

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

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

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

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

نص الطلب

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

يظهر أدناه مثال على نص طلب بيانات من واجهة برمجة التطبيقات للمواقع الجغرافية.

{
  "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 بت تجمع بين معرّف عقدة 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
    }
  ]
}

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

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

جارٍ الحساب newRadioCellId

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

• تستخدم شبكات NR (الجيل الخامس) معرّف خلية الراديو الجديد (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 التي تحتوي على macAddresses التي تكون إما عنوان بث (FF:FF:FF:FF:FF:FF) أو محجوزة من قِبل هيئة IANA إلى تحسين معدّل نجاح طلبات Geolocation API التي تستخدم شبكة Wi-Fi كمدخل. إذا تبيّن بعد الفلترة أنّ طلب بيانات من واجهة برمجة التطبيقات لرصد الموقع الجغرافي لن ينجح، يمكن استخدام إجراءات تخفيفية، مثل استخدام إشارات الموقع الجغرافي القديمة أو نقاط وصول Wi-Fi ذات الإشارات الأضعف. هذه الطريقة هي حل وسط بين حاجة تطبيقك إلى تقدير الموقع الجغرافي ومتطلبات الدقة والاسترجاع. توضّح تقنيات الفلترة التالية كيفية فلترة المدخلات، ولكنّها لا تعرض إجراءات التخفيف التي يمكنك اختيار تطبيقها بصفتك مهندس تطبيقات.

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

على سبيل المثال، يمكن جمع عناوين MAC صالحة للاستخدام في تحديد الموقع الجغرافي من مصفوفة سلاسل 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).

{
  "location": {
    "lat": 37.421875199999995,
    "lng": -122.0851173
  },
  "accuracy": 120
}

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