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

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

أهمية استخدام واجهة برمجة التطبيقات Address Validation API

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

قد تكون واجهة برمجة التطبيقات Geocoding API أكثر ملاءمةً لاحتياجاتك إذا لم تكن بحاجة إلى التحقّق من صحة مكوّنات العنوان الفردية. تعمل واجهة برمجة التطبيقات Geocoding API على تحويل العناوين إلى إحداثيات خط العرض وخط الطول. تتحقّق واجهة برمجة التطبيقات Address Validation API من صحة العناوين. اطّلِع على مقالة إنشاء ميزة التحقّق من الموقع الجغرافي باستخدام Google Maps Platform في مركز التصميم للحصول على مقارنة تفصيلية.

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

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

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

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

  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™

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

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

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

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

  1. "منصّة خرائط Google" هي مرخّص غير حصري لخدمة البريد الأمريكي ®. تملك خدمة البريد الأمريكي ® العلامات التجارية التالية وتستخدمها بإذن: خدمة البريد الأمريكي ® و CASS™ وCASS Certified™. ↩