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

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 بالإضافة إلى البيانات التي تعرضها. لمعرفة تفاصيل محدّدة، يُرجى الاطّلاع على مرجع 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™. ↩