الترميز الجغرافي هو عملية تحويل العناوين (مثل عنوان شارع) إلى إحداثيات جغرافية (خط العرض وخط الطول) يمكنك استخدامها لوضع علامات على خريطة أو تحديد موضع الخريطة. يهدف هذا المستند إلى توضيح الاعتبارات المعنيّة عند ترميز العناوين جغرافيًا. ويوضّح هذا القسم الحالات التي يكون فيها استخدام واجهة برمجة التطبيقات Geocoding API هو الخيار الأمثل والحالات التي يكون فيها استخدام خدمة "الإكمال التلقائي للأماكن" في واجهة برمجة التطبيقات Places API مفيدًا.
بشكل عام، استخدِم Geocoding API عند ترميز العناوين الجغرافية الكاملة (مثل "48 Pirrama Rd, Pyrmont, NSW, Australia"). استخدِم Places API خدمة "الإكمال التلقائي للأماكن" عند ترميز العناوين الغامضة (غير المكتملة) جغرافيًا أو لتطبيق يعتمد على وقت الاستجابة، مثل عند الردّ على إدخال المستخدم.
حالات الاستخدام واقتراحات واجهات برمجة التطبيقات
| حالات الاستخدام واقتراحات واجهات برمجة التطبيقات | |
|---|---|
| الاستجابة في الوقت الفعلي لبيانات المستخدم (تشمل العناوين الغامضة أو غير المكتملة أو ذات التنسيق السيئ أو التي تحتوي على أخطاء إملائية ويدخلها المستخدم) | استخدِم خدمة "الإكمال التلقائي للأماكن" من واجهة برمجة التطبيقات Places API للحصول على معرّف مكان، ثم استخدِم واجهة برمجة التطبيقات Geocoding API لتحويل معرّف المكان إلى إحداثيات جغرافية. |
| الأنظمة الآلية التي تعالج عناوين بريدية مكتملة وغير ملتبسة (على سبيل المثال، "48 Pirrama Rd, Pyrmont, NSW, Australia") | استخدام خدمة الويب Geocoding API |
| الأنظمة المبرمَجة التي تعالج طلبات بحث غامضة (على سبيل المثال، عناوين غير مكتملة أو ذات تنسيق سيئ أو بها أخطاء إملائية) | ننصحك بأن تستخدم الأنظمة المبرمَجة خدمة الويب Geocoding API. ومع ذلك، قد تستفيد الأنظمة المبرمَجة التي تسجّل معدّلًا مرتفعًا من طلبات البحث المُبهمة أو غير المكتملة أو التي تحتوي على أخطاء إملائية والمستمَدة من إدخال المستخدمين من إضافة أداة تفاعلية لميزة "إكمال الأماكن تلقائيًا" للسماح للمستخدمين باختيار نتيجة وبالتالي تجنُّب كتابة عنوان بشكلٍ خاطئ. |
| مشاكل وقت الاستجابة عند استخدام Directions API أو Distance Matrix API، مع تحديد نقاط البداية أو الوجهات أو نقاط الالتفاف على أنّها سلاسل عناوين | يمكنك تقليل وقت الاستجابة لميزة ترميز المواقع الجغرافية باستخدام خدمة ميزة "الإكمال التلقائي للأماكن" من Places API للحصول على أرقام تعريف الأماكن، ثم تمرير أرقام تعريف الأماكن إلى Directions API أو Distance Matrix API. |
الردّ على إدخال المستخدم
إنّ التطبيقات التي تستجيب في الوقت الفعلي لإدخال المستخدمين تتضمّن اعتبارَين رئيسيَّين يؤثّران في اختيار واجهة برمجة التطبيقات:
- تتضمن إدخالات المستخدمين بشكل عام إدخال عنوان تدريجيًا (مثل "123 شارع التحرير")، لذا فإنّ إمكانية ترميز العناوين غير المكتملة والمبهمة جغرافيًا تكون مفيدة لأنّها تتيح للمستخدم الحصول على نتيجة بشكل أسرع.
- إنّ التطبيقات التي تستجيب للبيانات التي يدخلها المستخدم تكون حساسة للغاية للوقت المستغرَق في معالجة البيانات.
تجعل هذه الاعتبارات خدمة "الإكمال التلقائي للأماكن" في Places API مثالية لحالة الاستخدام المتعلّقة بالردّ على إدخال المستخدم. تم تصميم ميزة "الإكمال التلقائي للأماكن" لعرض خيارات متعدّدة محتملة والسماح للمستخدم بالاختيار من بينها. يمكن تقييد واجهة برمجة التطبيقات Places API للبحث عن الرموز الجغرافية أو العناوين فقط مع استبعاد الأنشطة التجارية. بالإضافة إلى ذلك، يمكن أن تكون دالة البحث في ميزة الإكمال التلقائي منحازة لعرض نتائج خاصة بموقع جغرافي معيّن. تعرض واجهة برمجة التطبيقات Places APIمعرّف مكان يمكن تمريره كموقع جغرافي تمت إزالته بالكامل إلى خدمة الويب Geocoding API، التي بدورها تعرض تفاصيل العنوان بالكامل، وتُشفّر العنوان جغرافيًا إلى تنسيق latlng. يمكن أيضًا تمرير معرّفات الأماكن إلى واجهات برمجة تطبيقات أخرى، مثل Directions API و Distance Matrix API (راجِع المعلومات أدناه).
تُظهر عملية ترميز العناوين الجغرافية في Geocoding API وقت استجابة أعلى بكثير، كما تُظهر نتائج أقل دقة للطلبات غير المكتملة أو الغامضة، لذلك لا يُنصح باستخدامها في التطبيقات التي يجب أن تستجيب في الوقت الفعلي لمدخلات المستخدم.
يمكنك الحصول على مزيد من المعلومات عن خدمة "الإكمال التلقائي للأماكن" لنظامَي التشغيل Android، iOS، JavaScript، و Places API.
الأنظمة الآلية
الأنظمة المبرمَجة التي تعالج عناوين بريدية مكتملة وغير ملتبسة: إنّ طلبات البحث غير الملتبسة، مثل سلاسل عناوين بريدية مكتملة (مثل "48 Pirrama Rd, Pyrmont, NSW, Australia")، يتم التعامل معها على أفضل وجه من خلال خدمة ويب Geocoding API. توفّر الخلفية لتحويل العناوين إلى مواقع جغرافية تغطية أكبر للعناوين على مستوى العالم، وهي محسّنة للحصول على نتائج عالية الجودة باستخدام هذه الأنواع من طلبات البحث الكاملة وغير المتعدّدة التفسير.
النظام الآلي يعالج طلبات البحث الغامضة: الطلبات الغامضة هي تلك التي تحتوي على عناوين منسقة بشكلٍ سيئ أو عناوين غير مكتملة أو أخطاء إملائية. بالنسبة إلى الأنظمة المبرمَجة، ننصح باستخدام خدمة الويب Geocoding API. ومع ذلك، فإنّ واجهة برمجة التطبيقات Geocoding API غير مصمّمة للتعامل مع طلبات البحث المُبهمة، وقد تؤدي إلى عرض نتائج أقل دقة أو عدم عرض أي نتائج استجابةً لطلبات البحث المُبهمة. إذا كان نظامك المبرمَج يعالج معدّلًا مرتفعًا من طلبات البحث المُبهمة التي يتم الحصول عليها من إدخال المستخدم، يمكنك الاستفادة من إضافة عنصر تفاعلي إلى تطبيقك باستخدام خدمة الإكمال التلقائي للأماكن في Places API، لأنّه مصمّم لعرض خيارات متعدّدة محتملة والسماح للمستخدم بالاختيار بين هذه الخيارات. تعرض Places API رقم تعريف مكان يمكن تمريره كموقع جغرافي تم توضيحه بالكامل إلى خدمة الويب Geocoding API، التي بدورها تعرض تفاصيل العنوان بالكامل، وتُشفِّر العنوان جغرافيًا إلى تنسيق latlng. يمكنك الحصول على مزيد من المعلومات عن خدمة "الإكمال التلقائي للأماكن" لنظامَي التشغيل Android، iOS، JavaScript، و Places API.
تقليل وقت الاستجابة لواجهة برمجة التطبيقات Directions API و Distance Matrix API
عند تحديد نقاط البداية أو الوجهات أو نقاط الطريق على أنّها سلاسل عناوين، تستخدم Directions API و Distance Matrix API الخلفية نفسها المستخدَمة في واجهة برمجة التطبيقات Geocoding API لترميز هذه العناوين جغرافيًا قبل احتساب الاتجاهات. يؤدي ذلك إلى زيادة وقت الاستجابة بشكل كبير مقارنةً بتحديد المواقع الجغرافية نفسها باستخدام خطوط الطول والعرض أو معرّفات الأماكن.
إذا كان تطبيقك يستخدم Directions API أو Distance Matrix API في حالة حسّاسة للوقت المستغرَق في الردّ، مثل الاستجابة لإدخال المستخدم، ويتم تحديد نقاط البداية أو الوجهة أو نقاط الطريق في البداية على أنّها سلاسل عناوين، ننصحك بتقليل وقت الاستجابة إلى أدنى حدّ باستخدام خدمة الإكمال التلقائي للأماكن من Places API لتحويل سلاسل العناوين إلى معرّفات الأماكن، ثم تمرير معرّفات الأماكن إلى Directions API أو Distance Matrix API. يمكنك الحصول على مزيد من المعلومات عن خدمة "الإكمال التلقائي للأماكن" لنظامَي التشغيل Android وiOS وJavaScript و Places API. اطّلِع أيضًا على مثال على JavaScript لميزة "الإكمال التلقائي للأماكن" واتجاهات التنقّل.
الخاتمة
استنادًا إلى حالة الاستخدام، عند ترميز العناوين جغرافيًا، يتيح لك استخدام Geocoding API أو استخدام خدمة "الإكمال التلقائي للأماكن" مع Geocoding API إنشاء تطبيقات تقدّم للمستخدمين نتائج ترميز جغرافي دقيقة بالإضافة إلى وقت استجابة منخفض.
إدارة الأخطاء وعمليات إعادة المحاولة
إذا تلقّيت ردودًا من النوع UNKNOWN_ERROR، يعني ذلك أنّها ناجمة عن أخطاء مؤقتة
، وأفضل طريقة للتعامل معها هي إعادة المحاولة بعد فترة تأخير قصيرة. ننصح باستخدام
مكتبات
برامج عملاء خدمات الويب في "منصة خرائط Google" التي تتضمّن منطق إعادة المحاولة وتتوافق مع مصادقة
"خطة Google Maps Platform المميّزة".
إنّ مكتبة Java Client
وPython Client
وGo Client
وNode.js Client
لخدمات "خرائط Google" هي مكتبات عملاء تدعمها منتديات المطوّرين، وهي متاحة للتنزيل
والمساهمة فيها على GitHub، حيث يمكنك أيضًا العثور على تعليمات التثبيت
ونماذج الرموز البرمجية.
إذا تلقّيت رمز الحالة OVER_QUERY_LIMIT كردّ، يعني ذلك أنّه
تم تجاوز حدود الاستخدام لواجهة برمجة التطبيقات. ننصحك
بتجربة هذه
الاستراتيجيات المحسّنة للاستخدام.