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

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

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

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

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

نص الطلب

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

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

{
  "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 (الجيل الرابع) معرّف خلية 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 بت لتمرير رقم تعريف خلية الشبكة إلى واجهة برمجة التطبيقات رصد الموقع الجغرافي.

• تستخدم شبكات الجيل الخامس (NR) معرّف خلية الجيل الجديد (NCI) الذي يتألّف من 36 بت كما هو.
  النطاق المسموح به: 0 إلى 68719476735.

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

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

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

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

لا تُعدّ عناوين 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، لن يكون الطلب ناجحًا وستظهر رسالة خطأ (notFound) HTTP 404.

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

يعرض طلب الموقع الجغرافي الناجح استجابة بتنسيق JSON يحدِّد الموقع الجغرافي والنطاق.

• ‫location: إحداثيات خط العرض وخط الطول المقترَحة للمستخدم ، بالدرجات يحتوي على حقل فرعي واحد من النوع lat وحقل فرعي واحد من النوع lng.
• accuracy: دقة الموقع الجغرافي المقدَّر، بالقياس بال متر يمثّل هذا نصف قطر دائرة حول location المحدّد.

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