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

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

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

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

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

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

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

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

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

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

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

   • تقديم عنوان مقترَح للعميل لتأكيده:
     

   • الطلب من العميل إضافة المعلومات الناقصة:
     

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

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

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

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

جرِّب الإصدار التجريبي للاطّلاع على واجهة برمجة تطبيقات التحقّق من صحة العنوان أثناء تنفيذها.

المراجِع

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

موارد البيانات	البيانات المعروضة
معالجة العناصر بتنسيق JSON: يُرجى الاطّلاع على التحقّق من صحة العنوان.	عنوان كامل ومُصدَّق عليه (إن أمكن). حالة التحقق من كل مكون من مكونات العنوان الأماكن المتاحة لعنوان ما: الترميز الجغرافي دقة العنوان بيانات الخدمات البريدية، متى توفرت. راجِع فهم رد التحقّق.

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

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

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

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

لمحة عن CASSTM

تحتفظ شركة ®US Postal Service® (USPS®)¹ بـ نظام دعم دقة الترميز (CASSTM) لدعم مقدّمي خدمات التحقق من صحة العناوين واعتمادهم. تم تأكيد قدرتها على ملء المعلومات المفقودة من أحد العناوين وتوحيدها وتحديثها لمنحك أحدث وأدق عنوان من خدمات CASS المعتمَدة، مثل واجهة برمجة التطبيقات للتحقّق من صحة العنوان.

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

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

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

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