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

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

يتم إرسال طلبات الموقع الجغرافي باستخدام 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) رمز شبكة الجوّال لشبكة المنزل للجهاز هذا هو 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 في حال كانت إشارات Wi-Fi وبرج الاتصالات مفقودة أو فارغة أو غير كافية لتقدير الموقع الجغرافي للجهاز. الإعداد التلقائي هو true. اضبط considerIp على false لمنع الرجوع إلى الإعدادات السابقة.
cellTowers array مصفوفة من كائنات برج الاتصالات. راجِع قسم عناصر أبراج الجوّال أدناه.
wifiAccessPoints array مصفوفة من عناصر نقاط وصول WiFi راجِع قسم عناصر نقاط وصول Wi-Fi أدناه.

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

{
  "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 (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) رمز البلد حيث يتم تشغيل شبكة الجوّال (MCC) لبرج الاتصالات سمة مطلوبة لـ radioType gsm (التلقائية) وwcdma lte وnr، ولا تُستخدَم مع cdma.
النطاق المسموح به: من 0 إلى 999.
mobileNetworkCode number (uint32) رمز شبكة الجوّال لبرج الاتصالات وهذا هو MNC لـ GSM وWCDMA وLTE وNR.
يستخدم CDMA معرّف النظام (SID).		 مطلوبة
النطاق المسموح به لرقم تعريف شبكة الجوّال: من 0 إلى 999.
النطاق المسموح به لمعرّف الأمان (SID): من 0 إلى 32767.

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

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

احتساب 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 بت مع معرّف خلية بسعة 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، وجميع الحقول الأخرى اختيارية.

الحقل نوع ملف JSON الوصف ملاحظات
macAddress string عنوان MAC لوحدة Wi-Fi ويُعرف هذا العنوان عادةً باسم BSS أو BSSID أو عنوان MAC. مطلوبة: سلسلة سداسية عشرية مفصولة بنقطتَين (:)
يمكن العثور على عناوين MAC المُدارة عالميًا فقط من خلال واجهة برمجة التطبيقات. ويتم تجاهل عناوين MAC الأخرى بدون تنبيه، وقد يؤدي ذلك إلى أن يصبح طلب البيانات من واجهة برمجة التطبيقات فارغًا بشكل فعال. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة إيقاف نقاط الوصول إلى Wi-Fi غير المفيدة.
signalStrength number (double) قوة الإشارة الحالية مقاسةً بالديسيبل ميللي واط بالنسبة إلى نقاط اتصال Wi-Fi، تكون قيم ديسيبل عادةً -35 أو أقل وتتراوح بين -128 و-10 ديسيبل. احرص على تضمين علامة الطرح.
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 غير المستخدَمة

يمكن أن تؤدي إزالة عناصر نقاط وصول شبكة 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:

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
}