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

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

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

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

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

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

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

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

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

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

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

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

   • مطالبة العميل بإضافة معلومات غير متوفّرة:
     

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

آلية عمل التحقّق من صحة العنوان

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

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

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

الموارد

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

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

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

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

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

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

لمحة عن CASSTM

تحتفظ خدمة US Postal Service® (USPS® )¹ بنظام دعم دقة الترميز (CASSTM) لدعم مقدّمي خدمة التحقّق من العنوان واعتماده. لقد تم تأكيد خدمة TMCASS المعتمدة، مثل واجهة Address Address Verification API (إمكانية التحقّق من صحة العنوان) لإمكانية ملء المعلومات غير المتوفّرة في العنوان وتوحيدها وتعديلها لمنحك العنوان الأحدث والأكثر دقة.

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

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

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

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