Dokumen ini menjelaskan proses untuk mem-build sistem pemeriksaan alamat guna menangani berbagai respons dari Address Validation API. Panduan ini mencakup cara membangun logika untuk menggunakan respons dengan benar, menyelidiki sinyal lain dari API, serta kapan dan bagaimana cara meminta informasi lebih lanjut kepada pelanggan.
Secara umum, respons API menentukan cara berikut yang harus digunakan sistem Anda untuk menangani alamat:
- Perbaiki—alamat berkualitas rendah. Anda harus meminta informasi selengkapnya.
- Konfirmasi—alamat berkualitas tinggi, tetapi memiliki perubahan dari alamat input. Anda mungkin meminta konfirmasi.
- Setuju—alamat berkualitas tinggi. Anda dapat menerima alamat yang diberikan.
Tujuan utama
Dokumen ini membantu Anda memodifikasi sistem agar dapat menganalisis respons API dengan sebaik-baiknya dan menentukan tindakan berikutnya yang harus diambil dengan alamat yang disediakan. Kode semu berikut mengilustrasikan kemungkinan alur.
if (the API response indicates significant problems in the address)
FIX - prompt the user to fix the address
else if (the API response indicates less significant problems in the address)
CONFIRM - confirm with the user that the address is correct
else
ACCEPT - continue with the address returned by the API.
Logika yang tepat bergantung pada situasi Anda - lihat Panduan implementasi untuk detail selengkapnya. Anda juga dapat menggunakan implementasi open source logika ini, yang ada di Library Komponen yang Diperluas.
Ringkasan alur kerja
Tabel di bawah merangkum dua tindakan untuk sistem Anda:
- Alur kerja yang akan digunakan berdasarkan perilaku perbaikan, konfirmasi, dan terima.
- Sinyal pertama yang harus diperiksa dari respons. Sinyal yang dijelaskan di sini berasal dari properti
verdict
dan bukan satu-satunya sinyal yang harus diperiksa, tetapi memberikan indikator awal kualitas alamat. Setiap jenis perilaku sesuai dengan bagian dalam dokumen ini yang menjelaskan sinyal lebih lanjut yang mungkin juga perlu Anda selidiki.
Perilaku sistem Anda | |||
---|---|---|---|
Perbaiki alamat |
Respons dari
|
||
Konfirmasi alamat |
Respons dari
|
||
Setujui alamat |
Respons Address Validation API menunjukkan alamat berkualitas yang sangat baik.
|
Panduan implementasi
Saat mendesain cara sistem Anda merespons sinyal dari Address Validation API, rekomendasi berikut dapat membantu Anda membuat model respons yang lebih efektif. Namun, ini hanyalah rekomendasi, jadi perlu diingat bahwa penerapan Anda harus sesuai dengan model bisnis Anda.
Panduan | Detail | |
---|---|---|
Tingkat risiko |
Pertimbangkan tingkat toleransi terhadap situasi Anda saat menyeimbangkan antara meminta koreksi dan menerima alamat yang dimasukkan. |
Address Validation API menampilkan berbagai sinyal yang dapat Anda sertakan dengan level risiko untuk mengoptimalkan proses validasi Anda. Misalnya, jika alamat memiliki nomor jalan yang belum dikonfirmasi, Anda masih dapat menerimanya. Di sisi lain, jika operasi bisnis Anda memerlukan presisi alamat yang lebih tinggi, Anda dapat meminta izin kepada pengguna. Untuk melihat contoh yang bisa termasuk dalam salah satu kategori tersebut, lihat Nomor jalan yang belum dikonfirmasi di luar AS di bagian Terima alamat - contoh. |
Terima alamat |
Praktik yang baik adalah mengizinkan sistem Anda menerima entri asli jika pelanggan tidak merespons perintah. |
Dalam kasus ini, pelanggan mungkin telah memasukkan alamat yang tidak ada dalam sistem, seperti untuk konstruksi baru. |
Berikan masukan |
Saat mengajukan ulang permintaan validasi alamat, Anda juga dapat
mengirim permintaan ke endpoint |
Hal ini memungkinkan Google mengetahui bagaimana Anda pada akhirnya menangani respons akhir. Lihat Menangani alamat yang diperbarui. |
Memperbaiki alamat
Memperbaiki alamat jika hasilnya menunjukkan dengan jelas bahwa alamat tidak dapat dikirim. Sistem Anda kemudian dapat meminta pelanggan untuk memberikan informasi yang diperlukan, setelah itu Anda menerbitkan ulang alur kerja untuk mendapatkan alamat pengiriman.
Perbaiki sinyal
Address Validation API menyediakan sejumlah sinyal untuk memberi tahu Anda apakah alamat harus diperbaiki.
1. Perincian validasi dan komponen yang tidak ada
Kedua sinyal ini memberikan indikasi terbaik untuk alamat yang bermasalah:
- Setiap kali kolom
validationGranularity
adalahOTHER
, sistem Anda harus menyelidiki sinyal komponen alamat untuk mempelajari lebih lanjut tempat terjadinya error dan cara memperbaikinya. - Setiap kali objek
address
yang pasca-pemrosesan menampilkan kolommissingComponentTypes
, sistem Anda harus memeriksa komponen tersebut. Komponen yang tidak ada juga merender alamat yang tidak lengkap dan tidak dapat dikirimkan.
2. Sinyal lainnya
Address Validation API juga memberikan sinyal lain untuk membantu mendiagnosis masalah tertentu:
Komponen mencurigakan | Saat enum tingkat konfirmasi untuk komponen adalah UNCOMFIRMED_AND_SUSPICIOUS , kemungkinan komponen tersebut salah.
|
---|---|
Komponen yang belum di-resolve | unresolvedToken adalah bagian dari input yang tidak dikenali sebagai bagian yang valid dari sebuah alamat. |
3. Sinyal alamat AS
Kolom tertentu yang hanya berlaku untuk alamat di AS memberikan sinyal berguna bahwa alamat tidak dapat dikirim dan harus diperbaiki. Untuk alamat yang perlu diperbaiki, Anda akan melihat hal berikut:
dpvConfirmation
|
Berupa N , D , atau kosong.
|
---|
Untuk mengetahui detail tentang dpvConfirmation
, lihat
Menangani alamat di Amerika Serikat.
Konfirmasi alamat
Anda mengonfirmasi alamat saat verdict menunjukkan bahwa Address Validation API disimpulkan atau telah melakukan perubahan pada komponen alamat untuk menghasilkan alamat yang divalidasi. Dalam hal ini, Anda memiliki alamat pengiriman, tetapi lebih suka yakin bahwa alamat yang dihasilkan adalah alamat yang dimaksudkan oleh pelanggan.
Untuk memberi pelanggan permintaan yang benar, logika Anda akan mengidentifikasi
komponen yang ditandai oleh layanan untuk menentukan tindakan atau flag mana yang diterapkan API
pada komponen, seperti inferred
, replaced
, atau spellCorrected
.
Lihat AddressComponent dalam referensi.
Konfirmasi sinyal
Address Validation API menyediakan sejumlah sinyal untuk memberi tahu Anda apakah alamat harus dikonfirmasi.
1. Perincian Validasi
validationGranularity
sebesar ROUTE
atau yang lebih baik dapat diterima, tetapi
PREMISE atau SUBPREMISE memberikan sinyal pengiriman yang lebih kuat.
2. Sinyal lainnya
Saat memutuskan untuk mengonfirmasi entri alamat dengan pelanggan, verdict juga memberikan hal berikut untuk menentukan komponen yang perlu diselidiki:
Data yang disimpulkan | Jika kolom hasInferredComponents adalah true , Anda tahu bahwa API mengisi informasi yang diambil dari komponen alamat lainnya.
|
---|---|
Data yang diganti | Jika kolom hasReplacedComponents adalah true , API akan mengganti data yang dimasukkan dengan data yang dianggap membuat alamat tersebut valid.
|
3. Sinyal alamat AS
Kolom tertentu yang hanya berlaku untuk alamat di AS menunjukkan bahwa logika Anda harus mengonfirmasi detail dengan pelanggan. Salah satu hal berikut berlaku:
dpvConfirmation
|
S
Untuk mengetahui detail tentang |
---|---|
Respons alamat | Berisi kolom missingComponentType dengan nilai
subpremise .
|
Menerima alamat
Anda menerima alamat jika verdict memberikan tingkat keyakinan yang tinggi bahwa alamat tersebut dapat dikirim dan dapat digunakan tanpa interaksi pelanggan lebih lanjut dalam proses downstream.
Terima sinyal
Address Validation API menyediakan sejumlah sinyal untuk memberi tahu Anda apakah alamat harus dikonfirmasi.
1. Perincian Validasi
validationGranularity
yang bernilai PREMISE
atau lebih baik dapat diterima, tetapi dalam beberapa kasus, ROUTE
tetap menunjukkan alamat pengiriman.
2. Sinyal lainnya
Verdict untuk alamat berkualitas tinggi juga harus memberikan hal berikut:
- Tidak ada data yang diganti. Dalam hal ini,
hasReplacedComponents: FALSE
. - Tidak ada komponen yang disimpulkan. Dalam hal ini,
hasInferredComponents: FALSE
.
3. Sinyal alamat AS
Kolom tertentu yang hanya berlaku untuk alamat di AS menunjukkan alamat berkualitas tinggi yang dapat dikirim. Untuk alamat AS yang dapat diterima, Anda akan melihat hal berikut:
dpvConfirmation
|
Y
Untuk mengetahui detail tentang |
---|