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

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

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

الحقل نوع ملف 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
}