نظرة عامة على واجهة برمجة التطبيقات للتحقّق من العنوان
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
المطوّرون في المنطقة الاقتصادية الأوروبية
مقدمة
Address Validation API هي خدمة تقبل عنوانًا.
تحدّد هذه الخدمة مكوّنات العنوان وتتحقّق من صحتها. ويعمل أيضًا على توحيد تنسيق العنوان البريدي والعثور على أفضل إحداثيات معروفة لخطوط العرض/الطول الخاصة به.
يمكنك اختياريًا تفعيل
نظام دعم دقة الترميز (CASS™) للعناوين في الولايات المتحدة وبورتوريكو.
أسباب استخدام Address Validation API
باستخدام Address Validation API، يمكنك تحسين إمكانية توقّع عمليات التسليم وتقليل حالات فشل التسليم، ما يؤدي إلى تحسين تجربة العملاء. ويتم ذلك من خلال رصد العناوين غير الصالحة والتعرّف بشكل أفضل على خصائص العناوين.
قد يكون Geocoding API خيارًا أفضل لتلبية احتياجاتك إذا لم تكن بحاجة إلى التحقّق من صحة مكوّنات العنوان الفردية. تتيح Geocoding API
تحويل العناوين إلى إحداثيات خطوط العرض والطول. تتحقّق واجهة Address Validation API من صحة العناوين. يمكنك الاطّلاع على إمكانية التحقّق من صحة الموقع الجغرافي للمبنى باستخدام Google Maps Platform في "مركز التصميم" للحصول على مقارنة تفصيلية.
الإجراءات التي يمكنك تنفيذها باستخدام Address Validation API
inputتجربة العرض التوضيحي
باستخدام Address Validation API، يمكنك تحديد ما إذا كان العنوان يشير إلى مكان حقيقي. إذا كان العنوان لا يشير إلى مكان حقيقي، يمكن لواجهة برمجة التطبيقات تحديد المكوّنات التي قد تكون خاطئة والتي يمكنك عرضها على عملائك لتصحيحها. في ما يلي نموذج لسير العمل باستخدام واجهة برمجة التطبيقات:
إدخال العميل عنوانًا: تعرض الصورة التالية نموذجًا أساسيًا يتيح للعميل إدخال عنوان، ربما كجزء من عملية الدفع.
يرسل التطبيق العنوان إلى واجهة برمجة التطبيقات: يمرّر التطبيق هذا العنوان كإدخال إلى Address Validation API.
تتحقّق واجهة برمجة التطبيقات من صحة العنوان وتوحّده: في ردّها، تعرض واجهة Address Validation API العنوان الكامل كما حدّدته، أو تشير إلى المعلومات الناقصة.
تأكيد العميل للعنوان أو تصحيحه: بناءً على ما تعرضه واجهة برمجة التطبيقات، يمكنك تقديم الطلبات التالية إلى العميل:
أ. أكِّد العنوان المقترَح. ب. قدِّم المعلومات الناقصة.
ج. تصحيح العنوان
طريقة عمل 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™
تتولّى هيئة البريد الأمريكية (USPS®)1 إدارة
نظام دعم دقة الترميز (CASS™)
لتقديم الدعم لمقدّمي خدمات التحقّق من صحة العناوين واعتمادهم. تم تأكيد أنّ خدمة CASS Certified™، مثل Address Validation API، قادرة على ملء المعلومات الناقصة في العنوان وتوحيد تنسيقه وتعديله لتقديم العنوان الأحدث والأكثر دقة.
لا تكون ميزة CASS مفعّلة تلقائيًا، وهي متاحة فقط في منطقتَي "الولايات المتحدة" و "بورتوريكو". لتفعيل CASS، اضبط enableUspsCass على true كجزء من طلب التحقّق. لمزيد من المعلومات، يمكنك الاطّلاع على
التحقّق من صحة عنوان.
في إطار استخدامنا لخدمات USPS، تقيِّم هذه الشركة الطلبات المتعلقة بالعناوين التي تم إنشاؤها بشكل مصطنع. إذا رصدت هيئة البريد الأمريكية (USPS) أنّ عنوانًا تم إدخاله تم إنشاؤه بشكل مصطنع، على Google التوقّف عن التحقّق من صحة العناوين الخاصة بالعميل، وعليها إبلاغ هيئة البريد الأمريكية بمعلومات الاتصال الخاصة بالعميل (الاسم والعنوان) والعنوان ذي الصلة الذي تم إدخاله وبيانات الاستخدام المجمّعة. يعني استخدامك لواجهة برمجة التطبيقات موافقتك على بنود الخدمة الخاصة هذه.
الخطوات التالية
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-31 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe Address Validation API validates, standardizes, and geocodes addresses, improving delivery predictability and customer experience.\u003c/p\u003e\n"],["\u003cp\u003eIt identifies address components, validates them for correctness, and provides suggestions for corrections, unlike the Geocoding API, which only converts addresses to coordinates.\u003c/p\u003e\n"],["\u003cp\u003eAddresses are processed by correcting, completing, and formatting components, with CASS™ support for US and Puerto Rico addresses for enhanced accuracy (requires enabling).\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can access resources like a demo, coverage details, setup instructions, validation requests, response understanding, and client libraries to utilize the API effectively.\u003c/p\u003e\n"],["\u003cp\u003eUSPS evaluates requests for artificially created addresses, and Google is obligated to stop validation and report relevant information to USPS in such cases.\u003c/p\u003e\n"]]],["The Address Validation API validates and standardizes addresses, identifying components and correcting errors. It can infer missing information, and determine if an address is a real place. The API accepts an address, validates it, and returns a complete address or flags missing information. Users can confirm, correct, or provide missing details. For US and Puerto Rico addresses, CASS can be enabled for enhanced accuracy. The Geocoding API may be preferred if address component validation is not needed.\n"],null,["**European Economic Area (EEA) developers** If your billing address is in the European Economic Area, effective on 8 July 2025, the [Google Maps Platform EEA Terms of Service](https://cloud.google.com/terms/maps-platform/eea) will apply to your use of the Services. Functionality varies by region. [Learn more](/maps/comms/eea/faq). \n\nIntroduction The Address Validation API is a service that accepts an address. It identifies address components and validates them. It also standardizes the address for mailing and finds the best known latitude/longitude coordinates for it. Optionally, for addresses in the United States and Puerto Rico, you can enable the [Coding Accuracy Support System (CASS™)](https://developers.google.com/maps/documentation/address-validation/overview#about-cass).\n\nWhy use the Address Validation API\n\nWith the Address Validation API, you can improve delivery predictability and reduce\ndelivery failures, thereby providing improved customer experience. You do this\nby catching bad addresses and obtaining better awareness of address\ncharacteristics.\n\nThe Geocoding API might be a better match for your needs if you\ndon't need to validate the individual address components. The Geocoding API\n**converts** addresses into latitude and longitude coordinates. The\nAddress Validation API validates addresses for **correctness** . See\n[Building location validation capability using Google Maps Platform](https://developers.google.com/maps/architecture/geocoding-address-validation)\nin the Architecture Center for a detailed comparison.\n\nWhat you can do with the Address Validation API\n\n[inputTry the demo](/maps/documentation/address-validation/demo) [](/maps/documentation/address-validation/demo)\n\nWith the Address Validation API, you can determine if an address\nrefers to a real place. If the address does not refer to a real\nplace, the API can identify possibly wrong components that you can present to\nyour customers to correct. Here is a sample workflow using the API:\n\n1. **Customer enters an address** -- The following image shows a basic form\n that allows a customer to enter an address, possibly as part of a checkout\n flow.\n\n2. **App sends the address to the API** -- The application passes this address\n as the input to the Address Validation API.\n\n3. **API validates and standardizes the address** -- In its response, the\n Address Validation API returns the complete address as determined by the API, or\n indicates where information is missing.\n\n4. **Customer confirms or corrects the address** -- Depending on\n what the API returns, you can provide the following prompts to the customer:\n **A.** Confirm the recommended address. **B.** Provide missing information.\n **C.** Fix the address.\n\nHow the Address Validation API works\n\nThe address validation accepts a POST request with the address in the form\nof a JSON body. It separates the address into its individual components, and\nthen attempts the following:\n\n- **Corrects**---Provides component-level validation checks, including sub-premises where available.\n- **Completes**---Attempts to infer missing or incorrect address components.\n- **Formats**---Cleans up and standardizes the format for address components.\n\nResources\n\nThe following table summarizes the resources available through the\nAddress Validation API along with the data it returns. For specific details, see the\n[Address Validation API reference](./reference/rest).\n\n\u003cbr /\u003e\n\n| Data resources | Data returned |\n|-------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Address components in JSON format.** See [Validate an address](/maps/documentation/address-validation/requests-validate-address). | Complete, validated address (if possible). Validation status of each address component. Where available for an address: - Geocode - Address precision - Postal services data, where available. See [Understand the validation response](/maps/documentation/address-validation/understand-response). |\n\n\u003cbr /\u003e\n\nHow to use the Address Validation API\n\n|---|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| 1 | **Try the demo** | [Explore the demo](/maps/documentation/address-validation/demo) with a variety of address forms, both correct and incorrect. The demo provides a useful way to explore both the return values from the service, as well as the JSON formatted API response. |\n| 2 | **Check coverage** | Review [coverage details](/maps/documentation/address-validation/coverage) to see which countries and regions the Address Validation API supports. |\n| 3 | **Get set up** | Start with [Set up your Google Cloud project](/maps/documentation/address-validation/cloud-setup) and complete the instructions that follow. |\n| 4 | **Request an address validation** | Start with a basic address and then, for additional accuracy, you can enable CASS (for US and PR addresses only). See [Request an address validation.](/maps/documentation/address-validation/requests-validate-address) |\n| 5 | **Process a response** | The Address Validation API response provides two properties, each of which you use in different ways. See [Understand a basic response.](/maps/documentation/address-validation/understand-response) |\n| 6 | **Improve validation accuracy** | You can help improve address accuracy by providing feedback on Address Validation API responses. See [Handle updated addresses](/maps/documentation/address-validation/handle-updated-address). |\n\nAvailable client libraries\n\nFor a list of the available client libraries for Address Validation API,\nsee\n[Client libraries](/maps/documentation/address-validation/client_libraries).\n\nAbout CASS™\n\nThe United States Postal Service® (USPS®)^[1](#fn1)^ maintains the\n[Coding Accuracy Support System (CASS™)](https://postalpro.usps.com/certifications/cass)\nto support and certify address validation providers. A CASS Certified™ service,\nsuch as the Address Validation API, has been confirmed for its\nability to fill in information missing from an address, standardize it, and\nupdate it to give you the most current and most accurate address.\n\nCASS is not enabled by default and is only supported for the \"US\" and \"PR\"\nregions. To enable CASS, set `enableUspsCass` to `true` as part of a validation\nrequest. For more information, see\n[Validate an address](/maps/documentation/address-validation/requests-validate-address#enable-cass).\n\nAs part of our use of USPS services, USPS evaluates requests for artificially\ncreated addresses. If USPS identifies an input address as being artificially\ncreated, Google is required to stop validating addresses for the customer and\nmust report the customer's contact information (name and address), the relevant\ninput address, and aggregated usage data to USPS. By using the API you consent\nto these\n[Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms).\n\nWhat's next\n\n- **Try the demo** : Go to [Demo](/maps/documentation/address-validation/demo)\n- **Review coverage areas** : Go to [Country and region coverage details](/maps/documentation/address-validation/coverage)\n- **Try your first validation request** : Go to [Send an address validation request](/maps/documentation/address-validation/requests-validate-address)\n- **Process addresses at high volume** : Go to [Use Address Validation API to process addresses at high volume](/maps/architecture/high-volume-address-validation)\n\n*** ** * ** ***\n\n1. Google Maps Platform is a non-exclusive Licensee of the United States\n Postal Service®. The following trademark(s) are owned by the United States\n Postal Service® and used with permission: United States Postal Service®,\n CASS™, CASS Certified™. [↩](#fnref1)"]]
