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

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

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

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

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

نص الطلب

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

الحقل نوع JSON الوصف ملاحظات
homeMobileCountryCode number (uint32) رمز البلد المتنقل (MCC) لشبكة المنزل الخاصة بالجهاز متوافق مع radioType وgsm (تلقائي) وwcdma وlte وnr، ولا يُستخدَم مع cdma
النطاق الصالح: من 0 إلى 999.
homeMobileNetworkCode number (uint32) رمز شبكة الجوّال لشبكة المنزل الخاصة بالجهاز هذا هو رمز شبكة الجوّال لشبكات 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 في حال عدم توفّر إشارات Wi-Fi وأبراج الاتصالات أو إذا كانت فارغة أو غير كافية لتقدير الموقع الجغرافي للجهاز. القيمة التلقائية هي true. اضبط considerIp على false لمنع الرجوع إلى الإصدار السابق.
cellTowers array مصفوفة من عناصر أبراج الاتصالات يُرجى الاطّلاع على قسم عناصر برج الاتصالات أدناه.
wifiAccessPoints array مصفوفة من عناصر نقاط وصول Wi-Fi يُرجى الاطّلاع على قسم عناصر نقطة وصول شبكة 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
راجِع قسم احتساب cellId أدناه الذي يدرج أيضًا نطاقات القيم الصالحة لكل نوع من أنواع الراديو.
newRadioCellId number (uint64) المعرّف الفريد لخلية NR (الجيل الخامس). مطلوبة للنوعين 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) رمز البلد حيث يتم تشغيل شبكة الجوّال (MCC) لبرج الاتصالات مطلوبة لـ 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 (الجيل الخامس) الحقل 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 بت تجمع بين معرّف عقدة 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 (الجيل الخامس) معرّف خلية الراديو الجديد (NCI) المكوّن من 36 بت كما هو.
    النطاق الصالح: من 0 إلى 68719476735.

في ما يلي مثال على عنصر برج خلوي من الجيل الخامس.

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

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

يجب أن تحتوي مصفوفة wifiAccessPoints في نص الطلب على عنصرَين أو أكثر من عناصر نقاط وصول Wi-Fi التي تمثّل أجهزة نقاط وصول مختلفة فعليًا. macAddress مطلوب، وجميع الحقول الأخرى اختيارية.

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

يظهر أدناه مثال على عنصر نقطة وصول إلى شبكة 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 غير المستخدَمة

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

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

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 لشبكة Wi-Fi، لن ينجح الطلب وسيتم عرض الرد (notFound) HTTP 404.

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

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

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