نظرة عامة على واجهة برمجة التطبيقات للتحقّق من العنوان

المطوّرون المقيمون في المنطقة الاقتصادية الأوروبية

مقدمة

‫Address Validation API هي خدمة تقبل عنوانًا. وتحدّد مكوّنات العنوان وتتحقّق منها. كما تعمل على توحيد تنسيق العنوان لأغراض المراسلة وتحديد أفضل إحداثيات خطوط العرض والطول المعروفة له. يمكنك اختياريًا تفعيل نظام دعم دقة الترميز (CASS™)للعناوين في الولايات المتحدة وبورتوريكو.

أسباب استخدام Address Validation API

باستخدام Address Validation API، يمكنك تحسين إمكانية التنبؤ بعمليات التسليم وتقليل حالات فشل التسليم، ما يؤدي إلى تحسين تجربة العملاء. يمكنك تحقيق ذلك من خلال رصد العناوين غير الصالحة والتعرّف بشكل أفضل على خصائص العنوان.

اعتبارات أخرى

تتحقّق Address Validation API من صحة العناوين. بينما تحوّل Geocoding API العناوين إلى إحداثيات خطوط العرض والطول. للحصول على مقارنة تفصيلية، يُرجى الاطّلاع على مقالة إنشاء إمكانية التحقّق من صحة الموقع الجغرافي باستخدام "منصة خرائط Google" في مركز البنية.

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

تقدّم Geocoding API الإصدار 4 طريقة SearchDestinations التي تعرض إحداثيات لمداخل المباني ونقاط التنقّل ومخططاتها. لمزيد من التفاصيل، يُرجى الاطّلاع على قسم البحث عن الوجهات في Geocoding API الإصدار 4.

الإجراءات التي يمكنك تنفيذها باستخدام Address Validation API

تجربة العرض التوضيحي

باستخدام Address Validation API، يمكنك تحديد ما إذا كان العنوان يشير إلى مكان حقيقي. إذا لم يكن العنوان يشير إلى مكان حقيقي، يمكن لواجهة برمجة التطبيقات تحديد المكوّنات التي قد تكون خاطئة والتي يمكنك عرضها على عملائك لتصحيحها. في ما يلي نموذج لسير عمل باستخدام واجهة برمجة التطبيقات:

  1. يدخل العميل عنوانًا : تعرض الصورة التالية نموذجًا أساسيًا يتيح للعميل إدخال عنوان، ربما كجزء من عملية الدفع.

  2. يرسل التطبيق العنوان إلى واجهة برمجة التطبيقات : يمرّر التطبيق هذا العنوان كإدخال إلى Address Validation API.

    العنوان الذي أدخله العميل

  3. تتحقّق واجهة برمجة التطبيقات من صحة العنوان وتوحّد تنسيقه : في ردّها، تعرض Address Validation API العنوان الكامل كما تحدّده واجهة برمجة التطبيقات، أو تشير إلى المعلومات غير المتوفّرة.

  4. يؤكّد العميل العنوان أو يصحّحه : استنادًا إلى ما تعرضه واجهة برمجة التطبيقات، يمكنك تقديم المطالبات التالية للعميل: أ. تأكيد العنوان المقترَح ب. تقديم المعلومات غير المتوفّرة ج. تصحيح العنوان

    اطلب من العميل تأكيد العنوان كما تحدّده واجهة برمجة التطبيقات.اطلب من العميل إدخال معلومات العنوان الناقصة. اطلب من العميل تصحيح معلومات العنوان.

آلية عمل Address Validation API

تقبل عملية التحقّق من العنوان طلب POST يتضمّن العنوان في شكل نص JSON. وتفصل العنوان إلى مكوّناته الفردية، ثم تحاول تنفيذ ما يلي:

  • التصحيح : توفّر عمليات تحقّق من صحة المعلومات على مستوى المكوّنات، بما في ذلك المباني الفرعية متى توفّرت.
  • الإكمال: تحاول استنتاج مكوّنات العنوان غير المتوفّرة أو غير الصحيحة.
  • التنسيق: تنظّم تنسيق مكوّنات العنوان وتوحّده.

الموارد

يلخّص الجدول التالي الموارد المتاحة من خلال Address Validation API بالإضافة إلى البيانات التي تعرضها. للحصول على تفاصيل محدّدة، يُرجى الاطّلاع على المرجع Address Validation API.

مصادر البيانات البيانات المعروضة

مكوّنات العنوان بتنسيق JSON

يُرجى الاطّلاع على مقالة التحقّق من صحة عنوان.

عنوان كامل تم التحقّق من صحته (إذا أمكن)

حالة التحقّق من صحة كل مكوّن من مكوّنات العنوان

في حال توفّرها لعنوان معيّن:

  • الترميز الجغرافي
  • دقة العنوان
  • بيانات الخدمات البريدية، متى توفّرت

يُرجى الاطّلاع على مقالة فهم ردّ التحقّق من صحة المعلومات.

كيفية استخدام Address Validation API

1 تجربة العرض التوضيحي استكشف العرض التوضيحي باستخدام مجموعة متنوعة من نماذج العناوين، الصحيحة وغير الصحيحة. يوفّر العرض التوضيحي طريقة مفيدة لاستكشاف كلٍّ من القيم المعروضة من الخدمة واستجابة واجهة برمجة التطبيقات بتنسيق JSON.
2 التحقّق من التغطية يمكنك مراجعة تفاصيل التغطية للاطّلاع على البُلدان والمناطق التي تتيح فيها Address Validation API.
3 الإعداد ابدأ بمقالة إعداد مشروع Google Cloud وأكمِل التعليمات التالية.
4 طلب التحقّق من صحة عنوان ابدأ بعنوان أساسي، ثم يمكنك تفعيل نظام CASS (للعناوين في الولايات المتحدة وبورتوريكو فقط) لزيادة الدقة. يُرجى الاطّلاع على مقالة طلب التحقّق من صحة عنوان.
5 معالجة الردّ يوفّر ردّ Address Validation API سمتَين، تستخدم كلًّا منهما بطرق مختلفة. يُرجى الاطّلاع على مقالة فهم ردّ أساسي.
6 تحسين دقة التحقّق من صحة المعلومات يمكنك المساعدة في تحسين دقة العنوان من خلال تقديم ملاحظاتك على ردود Address Validation API. يُرجى الاطّلاع على مقالة التعامل مع العناوين المعدَّلة.

مكتبات العملاء المتاحة

للاطّلاع على قائمة بمكتبات العملاء المتاحة لـ Address Validation API، يُرجى الرجوع إلى مقالة مكتبات العملاء.

لمحة عن نظام CASS™‎

تتولى خدمة البريد في الولايات المتحدة (USPS®)1 إدارة نظام دعم دقة الترميز (CASS™) لدعم مقدّمي خدمات التحقّق من صحة العناوين واعتمادهم. تم التأكّد من قدرة الخدمة الحاصلة على شهادة CASS Certified™‎، مثل Address Validation API، على ملء المعلومات غير المتوفّرة في العنوان وتوحيد تنسيقه وتعديله لتزويدك بأحدث عنوان وأكثر دقة.

لا يكون نظام CASS مفعّلاً تلقائيًا ولا يتوفّر إلا للمنطقتَين "الولايات المتحدة" و"بورتوريكو". لتفعيل نظام CASS، اضبط enableUspsCass على true كجزء من طلب التحقّق من صحة المعلومات. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التحقّق من صحة عنوان.

كجزء من استخدامنا لخدمات USPS، تقيِّم USPS طلبات العناوين التي تم إنشاؤها بشكل مصطنع. إذا حدّدت USPS أنّ عنوان الإدخال تم إنشاؤه بشكل مصطنع، يجب على Google التوقّف عن التحقّق من صحة العناوين للعميل وعليها إبلاغ USPS بمعلومات الاتصال بالعميل (الاسم والعنوان) وعنوان الإدخال ذي الصلة وبيانات الاستخدام المجمّعة. باستخدام واجهة برمجة التطبيقات، أنت توافق على بنود الخدمة المحدّدة هذه .

الخطوات التالية

  1. ‫Google Maps Platform هي مرخِّص غير حصري لخدمة البريد في الولايات المتحدة (United States Postal Service®). تعود ملكية العلامات التجارية التالية إلى خدمة البريد في الولايات المتحدة (United States Postal Service®) ويتم استخدامها بإذن منها: United States Postal Service® و CASS™ وCASS Certified™‎. ↩