نظرة عامة

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

المقدمة

تعرض واجهة برمجة التطبيقات للموقع الجغرافي نطاقًا جغرافيًا ودقةً للموقع الجغرافي استنادًا إلى معلومات حول أبراج الاتصالات وعُقد WiFi التي يمكن لبرنامج الجوّال رصدها. يصف هذا المستند البروتوكول المستخدم لإرسال هذه البيانات إلى الخادم وعرض استجابة للعميل.

ويتم التواصل من خلال بروتوكول HTTPS باستخدام طريقة POST. يتم تنسيق كلٍّ من الطلب والاستجابة بتنسيق JSON، ويكون نوع محتوى كليهما application/json.

قبل البدء

قبل البدء في التطوير باستخدام Geolocation API، راجِع متطلبات المصادقة (تحتاج إلى مفتاح واجهة برمجة التطبيقات) ومعلومات استخدام واجهة برمجة التطبيقات والفوترة (عليك تفعيل الفوترة في مشروعك).

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

يتم إرسال طلبات الموقع الجغرافي باستخدام طلب 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. مع أن هذا الحقل اختياري، يجب تضمينه دائمًا إذا كان نوع البرنامج معروفًا للعميل.
إذا تم حذف الحقل، سيتم تلقائيًا ضبط واجهة برمجة تطبيقات رصد الموقع الجغرافي على gsm، ما سيؤدي إلى عرض نتائج غير صالحة أو صفر إذا لم يكن نوع الاختيار الذي تم افتراضه صحيحًا.
carrier string اسم شركة النقل
considerIp boolean يحدِّد هذا الإعداد ما إذا كان الرجوع إلى الموقع الجغرافي لعنوان IP في حال عدم توفّر إشارات شبكة Wi-Fi أو برج الهاتف الجوّال أو عدم توفّر أي من ذلك، أو إذا كان فارغًا أو غير كافٍ لتقدير الموقع الجغرافي للجهاز. القيمة التلقائية هي true. يمكنك ضبط considerIp على false لإيقاف الرجوع.
cellTowers array مصفوفة من عناصر برج الخلية. راجِع قسم كائنات برج الخلية أدناه.
wifiAccessPoints array مصفوفة من عناصر نقطة الوصول إلى شبكة Wi-Fi. يُرجى الاطّلاع على قسم كائنات نقطة الوصول إلى 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.
يُرجى الاطّلاع على القسم حساب خلية رقم الهاتف أدناه، والذي يسرد أيضًا نطاقات القيم الصالحة لكل نوع اختيار.
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).
إنّ هذه السمة مطلوبة.
نطاق صالح لرقم MNC: 0–999
نطاق صالح لمعرّف الأمان (SID): من 0 إلى 32767.

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

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

جارٍ حساب cellId

تستخدم أنواع الراديو التي تسبق NR (5G) الحقل cellId 32 بت لتمرير معرِّف خلية الشبكة إلى واجهة برمجة تطبيقات رصد الموقع الجغرافي.

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

  • تستخدم شبكات NR (5G) 36-bit Radio Cell Identity (NCI) كما هو.
    النطاق الصالح: 0–68719476735.

في ما يلي مثال لكائن برج اتصالات NR.

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

كائنات نقطة الوصول إلى شبكة Wi-Fi

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

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

في ما يلي مثال على عنصر نقطة وصول شبكة Wi-Fi.

{
  "macAddress": "9c:1c:12:b0:45:f1",
  "signalStrength": -43,
  "signalToNoiseRatio": 0,
  "channel": 11,
  "age": 0
}

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

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

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

الأخطاء

في حال حدوث خطأ، سيتم عرض نص استجابة عادية للتنسيق وسيتم ضبط رمز حالة HTTP على حالة الخطأ.

تحتوي الإجابة على كائن واحد في error يتضمن المفاتيح التالية:

  • code: هذه الحالة هي نفسها حالة HTTP للاستجابة.
  • message: وصف مختصر للخطأ
  • errors: قائمة بالأخطاء التي حدثت. ويحتوي كل خطأ على معرِّف لنوع الخطأ (reason) ووصف قصير (message).

على سبيل المثال، سيؤدي إرسال ملف JSON غير صالح إلى عرض الخطأ التالي:

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "parseError",
    "message": "Parse Error",
   }
  ],
  "code": 400,
  "message": "Parse Error"
 }
}

وتتضمن الأخطاء المحتملة ما يلي:

السبب النطاق رمز حالة HTTP الوصف
dailyLimitExceeded usageLimits 403 لقد تجاوزت الحد اليومي.
keyInvalid usageLimits 400 مفتاح واجهة برمجة التطبيقات غير صالح لواجهة برمجة تطبيقات رصد الموقع الجغرافي. ويُرجى التأكّد من تضمين المفتاح بالكامل، وشراء واجهة برمجة التطبيقات أو تفعيل الفوترة وتفعيل واجهة برمجة التطبيقات للحصول على الحصة بدون أي رسوم.
userRateLimitExceeded usageLimits 403 تم تجاوز حد الطلبات الذي أعددته في Google Cloud Console. يتم عادةً ضبط هذا الحد كطلبات في اليوم والطلبات لكل 100 ثانية والطلبات لكل 100 ثانية لكل مستخدم. ويجب ضبط هذا الحدّ لمنع مجموعة واحدة أو مجموعة صغيرة من المستخدمين من استنفاد حصتك اليومية، مع السماح في الوقت نفسه بالوصول المتاح لجميع المستخدمين. يُرجى الاطّلاع على استخدام Cloud API لضبط هذه الحدود.
notFound geolocation 404 كان الطلب صالحًا، ولكن لم يتم عرض أي نتائج.
parseError global 400 نص الطلب غير صالح JSON. يمكنك الرجوع إلى قسم نص الطلب للاطّلاع على تفاصيل حول كل حقل.

طلبات نموذجية

إذا كنت تريد تجربة واجهة برمجة التطبيقات للموقع الجغرافي مع عيّنة من البيانات، احفظ ملف JSON التالي في ملف:

{
  "considerIp": "false",
  "wifiAccessPoints": [
    {
      "macAddress": "3c:37:86:5d:75:d4",
      "signalStrength": -35,
      "signalToNoiseRatio": 0
    },
    {
      "macAddress": "94:b4:0f:fd:c1:40",
      "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.4241876,
      "lng": -122.0917381
  },
  "accuracy": 32.839
}

(اطّلِع على الحصول على مفتاح واجهة برمجة تطبيقات إذا لم يكن لديك مفتاح واجهة برمجة تطبيقات).

لإجراء اختبار إضافي، يمكنك جمع المعلومات من جهازك الذي يعمل بنظام التشغيل Android باستخدام حزمة تطوير البرامج (SDK) لأماكن Android وواجهات برمجة التطبيقات للموقع الجغرافي في Android، ومن جهازك الذي يعمل بنظام التشغيل iOS باستخدام حزمة تطوير البرامج (SDK) للأماكن التي تعمل بنظام التشغيل iOS.

الأسئلة الشائعة

لماذا أحصل على نطاق accuracy كبير جدًا في استجابة الموقع الجغرافي؟

إذا كانت استجابة الموقع الجغرافي تعرض قيمة عالية جدًا في الحقل accuracy، قد يتم تحديد الموقع الجغرافي للخدمة استنادًا إلى عنوان IP للطلب، بدلاً من نقاط WiFi أو أبراج الاتصالات. ويمكن أن يحدث ذلك في حال عدم وجود أبراج الاتصالات أو نقاط الوصول صالحة أو تم التعرّف عليها.

للتأكّد من أنّ هذه هي المشكلة، اضبط considerIp على false في طلبك. إذا كانت الاستجابة 404، تأكّدت من أنّه لا يمكن تحديد الموقع الجغرافي للكائنات wifiAccessPoints وcellTowers.