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

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

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

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

وإذا لم تكن بحاجة إلى التحقق من صحة مكونات العنوان الفردية لطلبك، قد تكون واجهة برمجة التطبيقات Geocode API مناسبة أكثر لاحتياجاتك. تعمل واجهة برمجة تطبيقات الترميز الجغرافي على تحويل العناوين إلى إحداثيات خطوط الطول والعرض، في حين أن واجهة برمجة التطبيقات للتحقق من صحة العناوين تتحقق من صحتها. لمعرفة التفاصيل، يُرجى الاطّلاع على آلية عمل واجهة برمجة التطبيقات الخاصة بالتحقق من صحة العناوين أدناه بالإضافة إلى نظرة عامة على واجهة برمجة التطبيقات للترميز الجغرافي.

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

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

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

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

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

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

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

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

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

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

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

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

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

المراجِع

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

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

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

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

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

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

لمحة عن CASSTM

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

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

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

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

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