تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

نظرة عامة

المقدمة

تعرض واجهة برمجة التطبيقات للموقع الجغرافي نطاقًا جغرافيًا ودقةً للموقع الجغرافي استنادًا إلى معلومات حول أبراج الاتصالات وعُقد 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.