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

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

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

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

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

الإجراءات التي يمكنك تنفيذها باستخدام واجهة برمجة التطبيقات 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®)¹ نظام دعم دقة الترميز (CASS™) لدعم مقدّمي خدمات التحقّق من العناوين واعتمادهم. تم تأكيد خدمة CASS Certified™، مثل Address Validation API، على قدرتها على ملء المعلومات غير المتوفّرة في العنوان وتوحيدها وتعديلها لمنحك أحدث عنوان وأكثره دقة.

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

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

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

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

---

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