التحقق من صحة العنوان

للتحقق من صحة العنوان باستخدام واجهة برمجة التطبيقات للتحقق من العنوان، يمكنك استدعاء طريقة validateAddress (REST) أو طريقة VerifyAddress (gRPC). يستخدم هذا المستند REST لأمثلةه، ولكن النهج يشبه gRPC.

بعد التحقق من صحة العنوان، يمكنك اختياريًا إعادة المعلومات إلى Google حول نتيجة التحقق من العنوان من خلال استدعاء طريقة provideValidationFeedback (REST) أو طريقة provideValidationFeedback (gRPC). للحصول على معلومات وأمثلة، راجع تقديم تعليقات حول التحقق من العنوان.

طلب التحقق من العنوان

يمكنك التحقق من صحة عنوان من خلال إرسال طلب POST إلى طريقة validateAddress:

https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY

تمرير نص JSON إلى الطلب الذي يحدد العنوان للتحقق من صحة:

curl -X POST -d '{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  }
}' \
-H 'Content-Type: application/json' \
"https://addressvalidation.googleapis.com/v1:validateAddress?key=YOUR_API_KEY"

يجب أن يحتوي الحقل address في نص الطلب، من النوع PostalAddress، على إدخال واحد على الأقل في addressLines.

• الحقل regionCode اختياري. في حال حذفه، تستنتج واجهة برمجة التطبيقات المنطقة من العنوان. ومع ذلك، لتحقيق أفضل أداء، ننصحك بتضمين regionCode إذا كنت تعرف ذلك. للحصول على قائمة بالمناطق المدعومة، راجع المناطق المدعومة.

• يقتصر إجمالي طول الحقل address على 280 حرفًا.

يمكنك اختياريًا تفعيل CATMTM عند التحقّق من صحة عنوان.

تحتفظ ¹ التابعة لـ US Postal Service® (USPS®)^{بنظام دعم دقة الترميز (CASSTM) لدعم مقدمي خدمة التحقق من العنوان واعتمادهم. تم تأكيد خدمة TMCASS المعتمدة، مثل واجهة برمجة تطبيقات التحقق من العنوان، بسبب قدرتها على ملء المعلومات المفقودة من أحد العناوين، وتوحيدها، وتحديثها لمنحك العنوان الحالي الأكثر دقة.}

بالنسبة إلى مناطق "الولايات المتحدة" و "PR"، فقط يمكنك اختياريًا تفعيل معالجة CASS من خلال ضبط enableUspsCass على true في نص الطلب.

للحصول على أفضل النتائج عند استخدام CASS، قدِّم عنوانًا يتضمن اسم الشارع ورقمه، إلى جانب المدينة والولاية والرمز البريدي:

{
  "address": {
    "regionCode": "US",
    "locality": "Mountain View",
    "administrativeArea": "CA",
    "postalCode": "94043",
    "addressLines": ["1600 Amphitheatre Pkwy"]
  },
  "enableUspsCass": true
}

يمكنك أيضًا تحديد العنوان الكامل ك سلسلتين في مصفوفة addressLines:

{
  "address": {
    "regionCode": "US",
    "addressLines": ["1600 Amphitheatre Pkwy", "Mountain View, CA, 94043"]
  },
  "enableUspsCass": true
}

استجابة التحقق من العنوان

وإذا نجح الطلب، سيستجيب الخادم برمز حالة HTTP 200 OK ونص استجابة يتضمن معلومات حول العنوان الذي تم التحقق من صحته.

يحتوي حقل الاستجابة result على كائن ValidationResult. يتضمن هذا الكائن:

• حقل address، من النوع العنوان، ويحتوي على معلومات تفصيلية عن العنوان.

• حقل geocode، من النوع الرمز الجغرافي، ويحتوي على معلومات حول الترميز الجغرافي للعنوان.

• حقل verdict، من النوع الحكم، ويحتوي على التحقق من العنوان ونتيجة الترميز الجغرافي.

• حقل metadata، من النوع AddressMetadata، يحتوي على البيانات الوصفية للعنوان.

• حقل uspsData، من النوع USPSData، ويحتوي على بيانات USPS للعنوان. هذه البيانات متاحة فقط للعناوين في الولايات المتحدة وبورتوريكو.

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

{
  "result": {
    "verdict": {
      "inputGranularity": "PREMISE",
      "validationGranularity": "PREMISE",
      "geocodeGranularity": "PREMISE",
      "addressComplete": true,
      "hasInferredComponents": true
    },
    "address": {
      "formattedAddress": "1600 Amphitheatre Parkway, Mountain View, CA 94043-1351, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043-1351",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "componentName": {
            "text": "1600",
            "languageCode": "en"
          },
          "componentType": "street_number",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Amphitheatre Parkway",
            "languageCode": "en"
          },
          "componentType": "route",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "Mountain View",
            "languageCode": "en"
          },
          "componentType": "locality",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "USA",
            "languageCode": "en"
          },
          "componentType": "country",
          "confirmationLevel": "CONFIRMED"
        },
        {
          "componentName": {
            "text": "94043"
          },
          "componentType": "postal_code",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "CA",
            "languageCode": "en"
          },
          "componentType": "administrative_area_level_1",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        },
        {
          "componentName": {
            "text": "1351"
          },
          "componentType": "postal_code_suffix",
          "confirmationLevel": "CONFIRMED",
          "inferred": true
        }
      ]
    },
    "geocode": {
      "location": {
        "latitude": 37.4223878,
        "longitude": -122.0841877
      },
      "plusCode": {
        "globalCode": "849VCWC8+X8"
      },
      "bounds": {
        "low": {
          "latitude": 37.4220699,
          "longitude": -122.084958
        },
        "high": {
          "latitude": 37.4226618,
          "longitude": -122.0829302
        }
      },
      "featureSizeMeters": 116.538734,
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g",
      "placeTypes": [
        "premise"
      ]
    },
    "metadata": {
      "business": false,
      "poBox": false
    },
    "uspsData": {
      "standardizedAddress": {
        "firstAddressLine": "1600 AMPHITHEATRE PKWY",
        "cityStateZipAddressLine": "MOUNTAIN VIEW CA 94043-1351",
        "city": "MOUNTAIN VIEW",
        "state": "CA",
        "zipCode": "94043",
        "zipCodeExtension": "1351"
      },
      "deliveryPointCode": "00",
      "deliveryPointCheckDigit": "0",
      "dpvConfirmation": "Y",
      "dpvFootnote": "AABB",
      "dpvCmra": "N",
      "dpvVacant": "N",
      "dpvNoStat": "Y",
      "carrierRoute": "C909",
      "carrierRouteIndicator": "D",
      "postOfficeCity": "MOUNTAIN VIEW",
      "postOfficeState": "CA",
      "fipsCountyCode": "085",
      "county": "SANTA CLARA",
      "elotNumber": "0103",
      "elotFlag": "A",
      "addressRecordType": "S"
    }
  },
  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

التحقق من صحة العنوان الذي تم تحديثه

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

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

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

على سبيل المثال، يتضمن الرد المعروض أعلاه الحقل responseId:

  "responseId": "de22bed8-7f52-44cb-8526-faceac57150a"

ستحتاج بعد ذلك إلى إعادة التحقق من صحة العنوان من خلال تغيير رقم الشارع من 1600 إلى 1500. عند إعادة التحقق من العنوان مرة أخرى، يجب تضمين الحقل previousResponseId مع قيمة responseId من الاستجابة الأولى:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a"
}

بالنسبة إلى الطلب باستخدام CASS:

{
  "address": {
    "regionCode" : "US",
    "locality" : "Mountain View",
    "addressLines" : ["1500 Amphitheatre Pkwy"]
  },
  "previousResponseId": "de22bed8-7f52-44cb-8526-faceac57150a",
  "enableUspsCass": true

}

تعرض نتائج كل مكالمة لاحقة قيمة جديدة في الحقل responseId. مع ذلك، يمكنك الاستمرار في تمرير قيمة responseId من الاستجابة الأولى في الحقل previousResponseId في جميع عمليات الاستدعاء اللاحقة لتحديثات العنوان.

حدث خطأ أثناء المعالجة

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

{
  "error": {
    "code": 403,
    "message": "The request is missing a valid API key.",
    "status": "PERMISSION_DENIED"
  }
}

إذا حذفت معلمة نص مطلوبة، مثل addressLines، ستعرض الطريقة ما يلي:

{
  "error": {
    "code": 400,
    "message": "Address lines missing from request.",
    "status": "INVALID_ARGUMENT"
  }
}

لمزيد من المعلومات حول الأخطاء والتعامل مع الأخطاء، راجع الأخطاء.