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

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

يتم إرسال طلبات الموقع الجغرافي باستخدام 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

تستخدم أنواع البث اللاسلكي قبل الجيل التالي (5G) حقل 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 (4G) معرّف خلية E-UTRAN (ECI)، وهو قيمة عددية تبلغ 28 بت تربط معرّف عقدة B في E-UTRAN الذي يبلغ 20 بت ومعرّف الخلية الذي يبلغ 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) معرّف خلية الجيل الجديد (NCI) الذي يتألف من 36 بت كما هو.
  النطاق المسموح به: 0 إلى 68719476735.

في ما يلي مثال على عنصر برج خلوي لشبكة الجيل التالي.

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

عناصر نقاط وصول شبكة WiFi

يجب أن تحتوي مصفوفة wifiAccessPoints في محتوى الطلب على عنصرَين أو أكثر من عناصر نقاط وصول WiFi التي تمثّل أجهزة نقاط وصول متميّزة بشكلٍ جسدي. الحقل macAddress مطلوب، وجميع الحقول الأخرى اختيارية.

في ما يلي مثال على عنصر نقطة وصول Wi-Fi.

{
  "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
}

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

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

إنّ عناوين MAC المُدارة محليًا ليست إشارات مفيدة للموقع الجغرافي لواجهة برمجة التطبيقات ويتم إسقاطها بصمت من الطلبات. يمكنك إزالة عناوين MAC هذه من خلال التأكّد من أنّ القيمة 0 هي القيمة الثانية الأقل أهمية في البايت الأكثر أهمية في macAddress، على سبيل المثال، الوحدة البتية 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:

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
}