یک درخواست اعتبار سنجی آدرس ارسال کنید

برای تأیید اعتبار یک آدرس با استفاده از Address Validation API، روش validateAddress (REST) ​​یا روش ValidateAddress (gRPC) را فراخوانی کنید. این مستندات از REST برای مثال های خود استفاده می کند، اما رویکرد مشابه با gRPC است.

پس از تأیید اعتبار یک آدرس، می‌توانید به صورت اختیاری با فراخوانی روش provideValidationFeedback (REST) ​​یا ProvideValidationFeedback (gRPC) اطلاعات مربوط به نتیجه اعتبارسنجی آدرس را به Google برگردانید. برای اطلاعات و مثال‌ها، به ارائه بازخورد تأیید اعتبار آدرس مراجعه کنید.

درخواست اعتبار سنجی آدرس

یک آدرس را با ارسال یک درخواست 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 اختیاری است. اگر حذف شود، API منطقه را از آدرس استنتاج می کند. با این حال، برای بهترین عملکرد، توصیه می‌کنیم در صورت اطلاع، regionCode وارد کنید. برای لیست مناطق پشتیبانی شده، به مناطق پشتیبانی شده مراجعه کنید.

  • طول کل قسمت address به 280 کاراکتر محدود شده است.

به صورت اختیاری، CASS™ را هنگام تأیید اعتبار یک آدرس فعال کنید

خدمات پستی ایالات متحده® (USPS®) 1 سیستم پشتیبانی دقت کدگذاری (CASS™) را برای پشتیبانی و تأیید ارائه دهندگان اعتبارسنجی آدرس حفظ می کند. یک سرویس CASS Certified™، مانند Address Validation 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 پاسخ حاوی یک شی ValidationResult است. این شی شامل:

  • یک فیلد address ، از نوع Address ، حاوی اطلاعات دقیق درباره آدرس.

  • یک فیلد geocode ، از نوع ژئوکد ، حاوی اطلاعات ژئوکد آدرس.

  • یک فیلد verdict ، از نوع 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"
}

یک آدرس به روز شده را تأیید کنید

در برخی موارد، ممکن است مجبور شوید چندین تماس با Address Validation API برای یک آدرس واحد برقرار کنید. به عنوان مثال، کاربر ممکن است پس از مشاهده نتایج اولین اعتبارسنجی، تغییرات یا اصلاحاتی در آدرس خود ایجاد کند. سپس اعتبار سنجی دوم را روی آدرس به روز شده انجام می دهید.

هر فراخوانی Address Validation API یک مقدار منحصر به فرد را در قسمت responseId پاسخ برمی گرداند. اگر آدرسی که می‌خواهید اعتبار سنجی کنید نیاز به تأیید مجدد دارد، responseId از اولین پاسخ تأیید اعتبار در قسمت previousResponseId برای همه درخواست‌های بعدی به Address Validation API ارسال کنید.

با گنجاندن قسمت previousResponseId در درخواست جدید، می‌توانید به ما در بهبود دقت کلی API کمک کنید.

به عنوان مثال، پاسخ نشان داده شده در بالا شامل فیلد 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 ادامه دهید.

رسیدگی به خطا

Address Validation API پیام های خطا را به عنوان بخشی از پاسخ به فراخوانی متد برمی گرداند. برای مثال، اگر کلید API را از درخواست حذف کنید، متد برمی‌گرداند:

{
  "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"
  }
}

برای اطلاعات بیشتر در مورد خطاها و رسیدگی به خطاها، به خطاها مراجعه کنید.

  1. Google Maps Platform یک دارنده مجوز غیر انحصاری از US Postal Service® است. علامت(های) تجاری زیر متعلق به US Postal Service® است و با مجوز استفاده می شود: US Postal Service®، CASS™، CASS Certified™. ↩