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

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

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

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

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

نص الطلب

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

في ما يلي مثال لنص طلب واجهة برمجة التطبيقات 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 لنص الطلب على أي عناصر أو أكثر من عناصر برج الاتصالات.

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

جارٍ احتساب 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 مطلوب، وجميع الحقول الأخرى اختيارية.

فيما يلي مثال على عنصر نقطة وصول 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
}