مرجع سريع حول Address Validation API

تقبل واجهة برمجة التطبيقات Address Validation API عنوانًا، وتحدّد مكوّناته وتتحقّق من صحتها، وتوحّد العنوان لإرسال البريد، وتعرض أفضل إحداثيات خطوط العرض/الطول المعروفة له. بالنسبة إلى العناوين في الولايات المتحدة وبورتوريكو، يمكنك تفعيل معالجة USPS CASS اختياريًا.

‫Address Validation API: معلومات أساسية

  • المنتج: Address Validation API
  • الفئة: الأماكن
  • المنصة: خدمة ويب (REST)
  • يتم تشغيله على: الخادم (رمز الخلفية)
  • مرحلة الإطلاق: GA
  • Lifecycle: نشط
  • نظرة عامة: نظرة عامة على Address Validation API
  • نطاق التوفّر الجغرافي: محدود تختلف البلدان المتاحة وجودة البيانات حسب البلد، وبعض البلدان في مرحلة "النسخة الحصرية". يتم عرض البيانات الوصفية السكنية والتجارية فقط للبلدان التي تم وضع علامة عليها في صفحة التغطية. يتوفّر نظام USPS CASS في الولايات المتحدة وبورتوريكو فقط. (تفاصيل التغطية)

‫Address Validation API: حالات الاستخدام

استخدام Address Validation API في الحالات التالية:

  • عليك التحقّق مما إذا كان العنوان يشير إلى مكان حقيقي والعثور على المكوّنات غير المضمّنة أو التي يُحتمل أن تكون خاطئة.
  • تحتاج إلى توحيد عنوان بريدي وإكماله، على سبيل المثال أثناء مسار الدفع.
  • يجب أن يكون لديك التحقّق من صحة العنوان وفقًا لنظام CASS التابع لخدمة البريد في الولايات المتحدة (USPS) وuspsData للعناوين في الولايات المتحدة أو بورتوريكو.
  • يجب توفّر بيانات وصفية لعنوان سكني أو تجاري في بلد مُدرَج في صفحة التغطية.

لا تستخدِم Address Validation API في الحالات التالية:

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

‫Address Validation API: الإعداد

حِزم Address Validation API الرسمية:

  • npm: @googlemaps/addressvalidation
  • pypi: google-maps-addressvalidation
  • go: cloud.google.com/go/maps

‫Address Validation API: الأخطاء الشائعة

  • المشكلة: يتم حذف السمة addressComplete من النتيجة عندما تكون قيمتها false، لذا فإنّ الرمز الذي يتوقع وجود الحقل يمكن أن يسيء قراءة العناوين غير المكتملة. الحلّ: يجب التعامل مع سمة addressComplete غير المتوفّرة على أنّها false، أو التحقّق من توفّر السمة. يُرجى الاطّلاع على /maps/documentation/address-validation/understand-response.
  • المشكلة: في حال حذف المَعلمة regionCode، تستنتج واجهة برمجة التطبيقات المنطقة من العنوان، ما قد يؤدي إلى نتائج أقل دقة. الحلّ: يجب تضمين regionCode في PostalAddress عندما يكون معروفًا. يُرجى الاطّلاع على /maps/documentation/address-validation/requests-validate-address.
  • المشكلة: لا نضمن تعبئة العنصر uspsData بالكامل لكل عنوان تم التحقّق منه في الولايات المتحدة. الحلّ: لا تعتمد على uspsData كإشارة التحقّق الوحيدة، بل استخدِم أيضًا مكوّنات العنوان والنتيجة. يُرجى الاطّلاع على /maps/documentation/address-validation/handle-us-address.
  • المشكلة: يجب أن تشير الملاحظات المُرسَلة باستخدام provideValidationFeedback إلى responseId من أول طلب validateAddress في التسلسل، وليس إلى طلب لاحق. الحلّ: يجب تخزين responseId من الردّ الأول على validateAddress وإرساله في طلب الملاحظات. يُرجى الاطّلاع على /maps/documentation/address-validation/handle-updated-address.

الإجراءات التي تتيح واجهة Address Validation API تنفيذها

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