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

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

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

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

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

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 حرفًا.

تفعيل خيار CASSTM عند اختيار عنوان

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

بالنسبة إلى المنطقتين "US" و "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 من الاستجابة كائن التحقّق من الصحة. ويتضمّن هذا الكائن ما يلي:

• حقل 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 all صالح

من خلال تضمين الحقل 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"
  }
}

للحصول على مزيد من المعلومات حول الأخطاء ومعالجة الأخطاء، يُرجى الاطّلاع على الأخطاء.