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

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

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

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

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

نص الطلب

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

الحقل نوع JSON الوصف ملاحظات
homeMobileCountryCode number (uint32) رمز البلد المخصّص للأجهزة الجوّالة (مركز عملائي) للشبكة الرئيسية للجهاز. متوافق مع radioType gsm (تلقائي)، wcdma وlte وnr، ولا يُستخدَم مع cdma.
النطاق الصالح: من 0 إلى 999.
homeMobileNetworkCode number (uint32) رمز شبكة الجوّال للشبكة المنزلية على الجهاز. هذا هو MNC لـ GSM وWCDMA وLTE وNR.
يستخدم CDMA معرّف النظام (SID)		 النطاق الصالح للحساب MNC: من 0 إلى 999.
النطاق الصالح لمعرّف الأمان (SID): من 0 إلى 32767.
radioType string نوع الراديو للأجهزة الجوّالة القيم المسموح بها هي gsm وcdma و wcdma وlte وnr على الرغم من أنّ هذا الحقل اختياري، يجب تضمينه دائمًا إذا كان نوع الاختيار هو يعرفها العميل.
إذا تم حذف الحقل، فسيتم ضبط القيمة التلقائية لواجهة برمجة التطبيقات Geolocation API على gsm، الذي سوف ينتج عنه نتائج غير صالحة أو لا ينتج عنها أي نتائج إذا كان نوع الاختيار المفترض غير صحيح.
carrier string اسم مشغِّل شبكة الجوّال
considerIp boolean لتحديد ما إذا كان سيتم الرجوع إلى رصد الموقع الجغرافي لعنوان IP في حال عدم توفّر إشارات WiFi أو برج الاتصالات. فارغة أو غير كافية لتقدير الموقع الجغرافي للجهاز وتكون القيمة التلقائية هي true. ضبط considerIp على false لمنع التراجع.
cellTowers array مصفوفة من كائنات برج الاتصالات. راجِع قسم عناصر أبراج الجوّال أدناه.
wifiAccessPoints array مصفوفة من عناصر نقطة وصول WiFi. راجِع قسم كائنات نقطة وصول Wi-Fi. أدناه.

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

الحقل نوع JSON الوصف ملاحظات
cellId number (uint32) المعرّف الفريد للخلية. مطلوبة لـ radioType gsm (الخيار التلقائي)، وcdma، wcdma وlte؛ تم الرفض لحساب nr.
راجع قسم حساب معرف الخلية أدناه، والذي يسرد أيضًا نطاقات القيم الصالحة لكل نوع من أنواع الاختيار.
newRadioCellId number (uint64) المعرّف الفريد لخلية NR (5G) مطلوبة لـ radioType nr مرفوضة لمواقع أخرى الأنواع.
راجِع قسم حساب newRadioCellId أدناه، التي تسرد أيضًا نطاق القيمة الصالح للحقل.
locationAreaCode number (uint32) رمز منطقة الموقع الجغرافي (LAC) لشبكات GSM وWCDMA.
رقم تعريف الشبكة (NID) لشبكات CDMA.
رمز منطقة التتبُّع (TAC) لشبكتَي LTE وNR.		 مطلوبة لـ radioType gsm (تلقائي) cdma، اختيارية للقيم الأخرى.
نطاق صالح مع gsm وcdma وwcdma و lte: 0–65535
النطاق الصالح مع nr: 0–16777215.
mobileCountryCode number (uint32) رمز البلد المتوافق مع الأجهزة الجوّالة (مركز عملائي) الخاص ببرج الاتصالات. مطلوبة لـ radioType gsm (الخيار التلقائي)، وwcdma، lte وnr؛ لم تُستخدَم لمدة cdma.
النطاق الصالح: من 0 إلى 999.
mobileNetworkCode number (uint32) رمز شبكة الجوّال لبرج الاتصالات. هذا هو MNC لـ GSM وWCDMA وLTE وNR.
يستخدم CDMA معرّف النظام (SID).		 يجب ملء هذا الحقل.
النطاق الصالح للحساب MNC: من 0 إلى 999.
النطاق الصالح لمعرّف الأمان (SID): من 0 إلى 32767.

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

الحقل نوع JSON الوصف ملاحظات
age number (uint32) عدد المللي ثانية منذ أن كانت هذه الخلية أساسية. إذا كانت قيمة العمر 0، يمثّل cellId أو newRadioCellId قيمة حالية القياس.
signalStrength number (double) تم قياس قوة الإشارة اللاسلكية بالديسيبل بالملي واط.
timingAdvance number (double) تشير رسالة الأشكال البيانية التقدم في التوقيت

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

الحقل نوع JSON الوصف ملاحظات
macAddress string عنوان MAC لعقدة WiFi. يطلق عليه عادةً عنوان BSS أو BSSID أو MAC. مطلوبة.سلسلة سداسية عشرية مفصولة بنقطتين (:).
فقط مُدار عالميًا يمكن تحديد موقع عناوين MAC عبر واجهة برمجة التطبيقات. عناوين MAC الأخرى هي يتم تجاهلها بدون قصد وقد يؤدي ذلك إلى أن يصبح طلب البيانات من واجهة برمجة التطبيقات فعالاً فارغ. لمعرفة التفاصيل، يمكنك الاطّلاع على استبعاد شبكة Wi-Fi عديمة الفائدة. نقاطك.
signalStrength number (double) قوة الإشارة الحالية تقاس بالديسيبل بالملي واط. بالنسبة إلى نقاط وصول WiFi، تكون قيم ديسيبل ميلي واط عادةً -35 أو أقل وتتراوح بين -128 و-10 ديسيبل ملي واط. احرص على تضمين علامة الطرح.
age number (uint32) عدد المللي ثانية منذ اكتشاف نقطة الوصول هذه
channel number (uint32) القناة التي يتصل من خلالها العميل بنقطة الوصول.
signalToNoiseRatio number (double) نسبة الإشارة إلى التشويش الحالية بالديسيبل.

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

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

إزالة عناصر نقطة وصول 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:

Java
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")));
Python
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')]
JavaScript
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
}