الترميز الجغرافي هو عملية تحويل العناوين (مثل عنوان الشارع) إلى إحداثيات جغرافية (خطوط العرض والطول) يمكنك استخدامها لوضع علامات على الخريطة أو تحديد موضع الخريطة. ينصب تركيز هذا المستند على توضيح الاعتبارات التي يجب مراعاتها عند الترميز الجغرافي للعناوين. وتوضّح الحالات التي يكون فيها من الأفضل استخدام Geocoding API والحالات التي يكون فيها من المفيد استخدام خدمة "الإكمال التلقائي للمكان" في Places API.
بشكل عام، استخدِم Geocoding API عند ترميز العناوين الكاملة جغرافيًا (على سبيل المثال، "48 Pirrama Rd, Pyrmont, NSW, Australia"). استخدِم خدمة الإكمال التلقائي للأماكن في Places API عند الترميز الجغرافي للعناوين الغامضة (غير المكتملة) أو للتطبيقات التي تتأثر بوقت الاستجابة، مثلاً عند الاستجابة لإدخالات المستخدمين.
حالات الاستخدام والاقتراحات بشأن واجهات برمجة التطبيقات
| حالات الاستخدام والاقتراحات بشأن واجهات برمجة التطبيقات | |
|---|---|
| الوصول الفعلي أو اختيار الوجهة المتقدّم أو التسليم إلى العميل النهائي أو الركوب/النزول من مركبة مشتركة أو مداخل المباني أو التنقّل في الحرم الجامعي | استخدِم طريقة البحث عن الوجهات (SearchDestinations) في الإصدار 4 من Geocoding API لاسترداد مداخل المباني ونقاط التنقّل القابلة للتوجيه ومخططات المباني والمعالم القريبة. يُرجى الاطّلاع على اختيار طريقة الترميز الجغرافي. |
| الاستجابة في الوقت الفعلي لإدخالات المستخدمين (بما في ذلك العناوين الغامضة أو غير المكتملة أو المنسَّقة بشكل سيئ أو التي تحتوي على أخطاء إملائية والتي يُدخلها المستخدم) | استخدِم خدمة "الإكمال التلقائي للأماكن" في Places API للحصول على
رقم تعريف المكان، ثم اطلب SearchDestinations (للحصول على تفاصيل على مستوى منطقة محلية صغيرة) أو GeocodePlace (للحصول على الإحداثيات الأساسية). |
| الأنظمة الآلية التي تعالج العناوين البريدية الكاملة والواضحة (على سبيل المثال، "48 Pirrama Rd, Pyrmont, NSW, Australia") | استخدِم خدمة الويب Geocoding API v4 (SearchDestinations للحصول على تفاصيل على مستوى منطقة محلية صغيرة أو GeocodeAddress للبحث عن الإحداثيات). |
| الأنظمة الآلية التي تعالج طلبات البحث الغامضة (على سبيل المثال، العناوين غير المكتملة أو المنسَّقة بشكل سيئ أو التي تحتوي على أخطاء إملائية) | ننصح الأنظمة الآلية باستخدام خدمة الويب Geocoding API. ومع ذلك، قد تستفيد الأنظمة الآلية التي تتضمّن معدّلًا مرتفعًا من طلبات البحث الغامضة أو غير المكتملة أو التي تحتوي على أخطاء إملائية والناتجة عن إدخال المستخدم من إضافة تطبيق مصغّر تفاعلي لخدمة "الإكمال التلقائي للأماكن" من أجل السماح للمستخدمين باختيار نتيجة وبالتالي تجنُّب كتابة عنوان بشكل خاطئ. |
| مشاكل في وقت الاستجابة عند استخدام Directions API (القديمة) أو Distance Matrix API (القديمة)، مع تحديد نقاط الانطلاق أو الوجهات أو النقاط على المسار كسلاسل عناوين | يمكنك تقليل وقت استجابة الترميز الجغرافي باستخدام خدمة "الإكمال التلقائي للأماكن" في Places API للحصول على أرقام تعريف الأماكن، ثم تمرير أرقام تعريف الأماكن إلى Directions API (الإصدار القديم) أو Distance Matrix API (الإصدار القديم). |
الردّ على إدخالات المستخدمين
هناك اعتباران رئيسيان يؤثران في اختيار واجهة برمجة التطبيقات للتطبيقات التي تستجيب في الوقت الفعلي لإدخالات المستخدم:
- يتضمن إدخال المستخدم بشكل عام إدخال عنوان بشكل تدريجي (مثل "123 شارع التحرير")، لذا فإن القدرة على الترميز الجغرافي للعناوين غير المكتملة والغامضة مفيدة لأنها تتيح للمستخدم الحصول على نتيجة بشكل أسرع.
- التطبيقات التي تستجيب لإدخالات المستخدمين حساسة للغاية لزمن الاستجابة.
هذان الاعتباران يجعلان خدمة "الإكمال التلقائي للأماكن" في Places API مثالية لحالة الاستخدام المتمثلة في الاستجابة لإدخالات المستخدمين. تم تصميم ميزة "الإكمال التلقائي للأماكن" لعرض خيارات متعددة محتملة والسماح للمستخدم بالاختيار من بينها. يمكن حصر Places API على البحث في الرموز الجغرافية أو العناوين فقط مع استبعاد المؤسسات. بالإضافة إلى ذلك، يمكن أن تكون دالة البحث في الإكمال التلقائي منحازة لعرض نتائج خاصة بموقع جغرافي معيّن. تعرض واجهة برمجة التطبيقات Places API رقم تعريف المكان الذي يمكن تمريره كموقع جغرافي تم توضيحه بالكامل إلى خدمة الويب Geocoding API، والتي تعرض بعد ذلك تفاصيل العنوان الكاملة، وتُرمِّز العنوان جغرافيًا إلى خطوط العرض والطول. يمكن أيضًا تمرير أرقام تعريف الأماكن إلى واجهات برمجة تطبيقات أخرى، مثل 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، والتي تعرض بعد ذلك تفاصيل العنوان الكاملة، وتُرمِّز العنوان جغرافيًا إلى خط عرض وخط طول. يمكنك الحصول على مزيد من المعلومات حول خدمة "الإكمال التلقائي للأماكن" لنظام التشغيل 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 وحدها أو دمجها مع خدمة "الإكمال التلقائي للأماكن". يتيح لك ذلك إنشاء تطبيقات تقدّم نتائج دقيقة للترميز الجغرافي وزمن انتقال أقل.
إدارة الأخطاء وإعادة المحاولة
إذا تلقّيت ردودًا من النوع UNKNOWN_ERROR، يعني ذلك أنّها ناتجة عن أخطاء مؤقتة،
ومن الأفضل التعامل معها من خلال إعادة المحاولة بعد فترة تأخير قصيرة. ننصحك بالاستفادة من
مكتبات برامج خدمات الويب في "منصة خرائط Google" التي تتضمّن منطق إعادة المحاولة وتتوافق مع مصادقة الخطة المميّزة في "منصة خرائط Google".
عميل Java وعميل Python وعميل Go وعميل Node.js لخدمات "خرائط Google" هي مكتبات عملاء يتيحها المنتدى، وهي متاحة للتنزيل والمساهمات على GitHub، حيث ستجد أيضًا تعليمات التثبيت والرمز النموذجي.
إذا تلقّيت رمز الحالة OVER_QUERY_LIMIT كردّ، يعني ذلك أنّك تجاوزت حدود الاستخدام لواجهة برمجة التطبيقات. ننصحك
بتجربة
استراتيجيات تحسين الاستخدام هذه.