Memahami respons validasi alamat dasar

Address Validation API memberikan isi respons sebagai objek JSON yang berisi dua properti tingkat teratas:

• result, objek dengan jenis ValidationResult
• responseID

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

Dokumen ini berfokus pada objek result. Untuk mengetahui informasi tentang responseID, lihat Menangani alamat yang diperbarui.

Properti verdict

Properti verdict merangkum hasil validasi alamat dan harus menjadi properti pertama yang dievaluasi saat membangun logika pemeriksaan alamat. Properti ini dapat menampilkan berbagai kolom, bergantung pada kualitas alamat output. Misalnya, berikut menunjukkan properti verdict dari alamat berkualitas baik, yang menampilkan 4 kolom untuk permintaan khusus ini:

"verdict": {
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true,
  "possibleNextAction": "ACCEPT"
}

Bagian berikut merangkum semua kolom di properti verdict.

Kemungkinan tindakan selanjutnya

Properti possibleNextAction menawarkan ringkasan interpretatif dari respons API lainnya, dengan tujuan membantu Anda menentukan apakah Anda harus meminta pelanggan meninjau atau mengedit alamat mereka. Lihat Membangun logika validasi untuk mengetahui detail selengkapnya.

Tingkat perincian alamat

Tingkat perincian alamat mengacu pada tingkat detail yang digunakan dalam menentukan spesifisitas alamat atau geocode. Kekhususan alamat dalam respons validationGranularity adalah sinyal utama untuk menentukan apakah alamat dapat digunakan untuk pengiriman atau tidak.

Properti verdict menampilkan sinyal perincian berikut:

• inputGranularity — Menjelaskan tingkat detail yang diambil dari alamat yang dikirim ke Address Validation API. Tingkat detail alamat dalam permintaan memengaruhi tingkat detail alamat dalam respons validasi. Misalnya, alamat dengan inputGranularity di bawah PREMISE di bawah tingkat biasanya tidak menghasilkan validationGranularity ke tingkat PREMISE.
• validationGranularity — Tingkat perincian yang dapat digunakan Address Validation API untuk memvalidasi alamat sepenuhnya. Dalam sebagian besar kasus, tingkat perincian PREMISE atau SUB_PREMISE menunjukkan alamat berkualitas yang kemungkinan dapat dikirim.
• geocodeGranularity — Mendeskripsikan tingkat detail geocode yang terkait dengan alamat. Misalnya, catatan Google mungkin menunjukkan keberadaan nomor apartemen, tetapi bukan lokasi yang tepat untuk apartemen tertentu tersebut dalam kompleks apartemen besar. Dalam hal ini, validationGranularity adalah SUB_PREMISE, tetapi geocodeGranularityisPREMISE`.

Kelengkapan alamat

Hasil putusan menampilkan properti addressComplete sebagai sinyal untuk alamat berkualitas tinggi, yang berarti secara khusus tidak memiliki komponen yang hilang, belum terselesaikan, atau tidak terduga:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "PREMISE",
    "geocodeGranularity": "PREMISE",
    "addressComplete": true,
    "possibleNextAction": "ACCEPT"
}

Jika alamat memiliki komponen yang tidak ada, belum terselesaikan, atau tidak terduga, kolom disetel ke false.

Kualitas alamat

Sejumlah kemungkinan kolom menunjukkan masalah pada komponen alamat, atau penyesuaian pada komponen alamat, seperti komponen alamat yang disimpulkan atau tidak ada. Misalnya, properti verdict berikut menunjukkan alamat dengan komponen yang belum dikonfirmasi dan kolom addressComplete yang tidak ada:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}

Properti address dan addressComponent

Properti address memberikan format untuk alamat yang diproses yang diberikan dalam permintaan, beserta ringkasan tingkat komponen dari alamat, termasuk bagian alamat yang salah eja, bagian yang salah yang diganti, dan bagian yang hilang yang disimpulkan.

Properti addressComponent adalah subkomponen address yang memberikan daftar mendetail elemen—atau komponen—alamat yang telah diproses oleh Address Validation API. API mengidentifikasi setiap kolom komponen yang disediakan berdasarkan nama, jenis, dan tingkat konfirmasi.

Properti geocode

Properti geocode menunjukkan lokasi yang di-geocode yang terkait dengan alamat input. Properti ini memberikan detail tentang lokasi itu sendiri, seperti ID tempatnya.

Properti metadata

Properti ini mungkin tidak diisi untuk setiap alamat yang diproses oleh Address Validation API, tetapi menunjukkan apakah alamat tersebut berjenis rumah, bisnis, atau PO Box.

Properti uspsData

Properti ini memberikan informasi yang berguna untuk alamat pos di Amerika Serikat. Namun, kolom ini tidak dijamin akan terisi sepenuhnya untuk setiap alamat yang divalidasi oleh layanan. Oleh karena itu, Anda tidak boleh mengandalkan properti ini sebagai satu-satunya cara untuk memvalidasi alamat, tetapi periksa verdict dan address juga.