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

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

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

• تستخدم شبكات GSM (2G) معرِّف الخلية 16 بت (CID) كما هو. النطاق الصالح: من 0 إلى 65535.
• تستخدم شبكات CDMA (2G) رقم تعريف المحطة الأساسية 16 بت (BID) كما هو. النطاق الصالح: من 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 بت تنسيق 64 بت newRadioCellId لتمرير معرّف الخلية في الشبكة إلى واجهة برمجة التطبيقات 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 غير المستخدمة

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

عناوين MAC التي تتم إدارتها محليًا ليست إشارات موقع مفيدة واجهة برمجة التطبيقات (API) ويتم تجاهلها تلقائيًا من الطلبات. يمكنك إزالة عناوين 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 لشبكة WiFi، فلن ينجح الطلب وظهر HTTP 404 (notFound) والاستجابة.

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

يؤدي طلب رصد الموقع الجغرافي الناجح إلى عرض استجابة بتنسيق JSON تحديد الموقع ونصف القطر.

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

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