تقبل واجهة برمجة التطبيقات 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: الإعداد
- الخدمة المطلوب تفعيلها:
addressvalidation.googleapis.com - المصادقة: مفتاح واجهة برمجة التطبيقات، وOAuth 2.0، وحساب الخدمة
- البدء: إعداد Address Validation API
- المرجع: مرجع Address Validation API
- الأسعار: استخدام Address Validation API والفوترة
- السياسات: سياسات Address Validation 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 تنفيذها
يمكنك الاطّلاع على الأدلة المرتبطة أدناه لكل مهمة، أو المقارنة بين المنتجات في مستكشف الإمكانات.
- عرض عنوان تم التحقّق منه لعنوان محدّد أو عنوان جزئي
- عرض إحداثيات خطوط العرض/الطول لعنوان تم التحقّق منه
- عرض معرّف المكان على Google لعنوان تم التحقّق منه
- استخدام شهادة "نظام دعم دقة الترميز" (CASS) الصادرة عن "خدمة البريد في الولايات المتحدة" (USPS) للتحقّق من العنوان:
- يمكنك الحصول على معلومات حول ما إذا كان العنوان الذي تم التحقّق منه هو عنوان مؤسسة أو سكن أو صندوق بريد.
- عرض البيانات الوصفية لعمليات التسليم التي تتم من خلال خدمة البريد في الولايات المتحدة (USPS) لعنوان تم التحقّق منه
- عرض نسخة باللغة الإنجليزية من عنوان تم التحقّق منه معاينة
- عرض رمز Plus Code لعنوان تم التحقّق منه