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

نظرة عامة على التحقّق من العنوان

واجهة برمجة تطبيقات التحقق من صحة العنوان هي خدمة تقبل عنوانًا. يحدد مكونات العنوان ويتحقق من صحتها. كما أنه يوحّد العنوان للبريد ويجد أفضل إحداثيات خطوط الطول/العرض له. اختياريًا، بالنسبة إلى العناوين في الولايات المتحدة وبورتوريكو، يمكنك تفعيل نظام دعم دقة الترميز (CASSTM).

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

باستخدام واجهة برمجة تطبيقات التحقق من صحة العناوين، يمكنك تحسين إمكانية توقع التسليم وتقليل حالات تعذُّر التسليم، ما يؤدي بدوره إلى تحسين تجربة المستخدم. يمكنك القيام بذلك عن طريق التقاط العناوين السيئة والحصول على وعي أفضل بخصائص العنوان.

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

الإجراءات التي يمكنك تنفيذها باستخدام واجهة برمجة تطبيقات التحقق من صحة العنوان

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

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

  2. يرسل التطبيق العنوان إلى واجهة برمجة التطبيقات – يمرر التطبيق هذا العنوان كإدخال إلى واجهة برمجة تطبيقات التحقق من صحة العنوان.

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

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

    • قدِّم عنوانًا مقترَحًا للعميل لتأكيده:
      اطلب من العميل تأكيد العنوان على النحو الذي تحدّده واجهة برمجة التطبيقات.

    • الطلب من العميل إضافة المعلومات الناقصة:
      اطلب من العميل إدخال معلومات العنوان غير المتوفّرة.

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

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

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

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

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

المراجع

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

موارد البيانات تم إرجاع البيانات

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

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

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

حالة التحقق من كل مكون عنوان.

حيثما كان ذلك متاحًا لعنوان:

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

يمكنك الاطّلاع على مقالة فهم الردّ الذي تم التحقّق من صحته.

كيفية استخدام واجهة برمجة تطبيقات التحقق من صحة العنوان

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

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

للحصول على قائمة بمكتبات العملاء المتاحة لواجهة برمجة تطبيقات التحقق من صحة العناوين، يُرجى الاطّلاع على مكتبات العملاء.

لمحة عن CASSTM

تحتفظ ®USPS® (USPS®)1 بنظام دعم دقة الترميز (CASSTM) لدعم مقدّمي خدمات التحقّق من العناوين واعتمادهم. تم التأكد من إحدى خدمات TMCASS المعتمَدة، مثل واجهة برمجة تطبيقات التحقق من صحة العناوين، وذلك بفضل قدرتها على ملء المعلومات المفقودة من أحد العناوين وتوحيدها وتحديثها لمنحك العنوان الأحدث والأكثر دقة.

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

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

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

  1. إنّ "منصة خرائط Google" هي جهة مرخّص لها بشكل غير حصري في ®Mail Service® في الولايات المتحدة. والعلامة(العلامات التجارية) التالية مملوكة لشركة Postal Service® في الولايات المتحدة ويتم استخدامها بإذن: US Postal Service® أو CASSTM أو CASS CertificateTM ↩