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

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

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

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

يجب تحديد مفتاح في طلبك، ويتم تضمينه كقيمة لمَعلمة key. ‫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 (5G) حقل cellId المكوّن من 32 بت لتمرير معرّف خلية الشبكة إلى Geolocation API.

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

إسقاط نقاط وصول WiFi غير المستخدَمة

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

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

يؤدي طلب تحديد الموقع الجغرافي الناجح إلى عرض ردّ بتنسيق 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 ديسيبل ميللي واط).
  • الخلايا الصغيرة (مثل الخلايا الفيمتو أو الخلايا البيكو أو أجهزة تكرار الإشارة الداخلية) توفّر الموقع الجغرافي الأكثر دقة استنادًا إلى الخلايا، مع نصف قطر دقة يمكن أن يتراوح بين 10 و30 مترًا.
• تحديد الموقع الجغرافي لعنوان IP: إذا كانت قيمة considerIp هي true ولم يكن بالإمكان تحديد الموقع الجغرافي لإشارات شبكة Wi-Fi أو برج الاتصالات، تقدِّر واجهة برمجة التطبيقات الموقع الجغرافي استنادًا إلى عنوان IP الخاص بالطلب. توفّر هذه الطريقة أقل دقة، مع أنصاف أقطار يمكن أن تصل إلى آلاف الأمتار. راجِع القسم لماذا نصف قطر الدقة كبير جدًا؟ في دليل تحديد المشاكل وحلّها