Membuat logika validasi

Dokumen ini menjelaskan proses untuk membangun sistem pemeriksaan alamat guna menangani berbagai respons dari Address Validation API. Panduan ini mencakup cara membangun logika agar dapat menggunakan respons dengan benar, menyelidiki sinyal lain dari API, serta waktu dan cara meminta informasi selengkapnya dari pelanggan.

Secara umum, respons API menentukan cara berikut yang 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 untuk menganalisis respons API dengan sebaik-baiknya dan menentukan tindakan berikutnya yang akan diambil dengan alamat yang diberikan. 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 tepatnya bergantung pada situasi Anda - lihat Panduan penerapan 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 ini merangkum dua tindakan untuk sistem Anda:

1. Alur kerja yang akan digunakan berdasarkan perilaku perbaikan, konfirmasi, dan penerimaan.
2. Sinyal pertama yang akan diperiksa dari respons. Sinyal yang dijelaskan di sini berasal dari properti verdict dan bukan satu-satunya sinyal yang perlu 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 alamatnya	Respons dari verdict menunjukkan informasi penting yang tidak ada dan harus diberikan. Alamat yang ditampilkan oleh Address Validation API mungkin tidak memiliki kualitas yang dapat diberikan. Alur kerja Selidiki komponen alamat jika perlu. Meminta pelanggan untuk memperbaiki masalah. Minta validasi untuk alamat yang diperbarui. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Baca bagian Menangani alamat yang diperbarui. Lanjutkan dengan alamat. Sinyal verdict Salah satu hal berikut berlaku: validationGranularity disetel ke OTHER. Lihat nilai detail. addressComplete adalah false.
Konfirmasi alamat	Respons dari verdict menunjukkan alamat pengiriman, tetapi telah melakukan perubahan pada input asli: menyimpulkan data yang ejaannya sudah dikoreksi, atau data yang dapat dikonfirmasi. Alur kerja Koreksi diperlukan: Selidiki komponen alamat jika perlu. Minta validasi untuk alamat yang diperbarui. (Opsional) Kirim permintaan ke endpoint masukan untuk API. Baca bagian Menangani alamat yang diperbarui. Lanjutkan dengan alamat. Tidak perlu koreksi: (Opsional) Kirim permintaan ke endpoint masukan untuk API. Baca bagian Menangani alamat yang diperbarui. Lanjutkan dengan alamat. Sinyal verdict Semua hal berikut berlaku: validationGranularity berisi ROUTE atau yang lebih baik. Lihat nilai detail. addressComplete adalah true. Kolom hasInferredComponents adalah true ATAU kolom hasReplacedComponents adalah true.
Terima alamat	Respons Address Validation API menunjukkan alamat dengan kualitas yang sangat baik. Alur kerja Lanjutkan dengan alamat yang dikembalikan. Sinyal verdict Semua hal berikut berlaku: validationGranularity berisi PREMISE atau yang lebih baik. Lihat nilai granularity. addressComplete adalah true. Tidak ada komponen yang disimpulkan atau diganti.

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 gabungkan dengan tingkat risiko untuk mengoptimalkan proses validasi. Misalnya, jika suatu alamat memiliki nomor jalan yang belum dikonfirmasi, Anda tetap dapat menerimanya. Di sisi lain, jika operasi bisnis Anda memerlukan presisi alamat yang lebih baik, Anda dapat meminta izin kepada pengguna. Untuk contoh yang dapat termasuk dalam salah satu kategori, lihat Nomor jalan yang belum dikonfirmasi di non-AS di Alamat penerimaan - contoh.
Terima alamat	Sebaiknya izinkan sistem Anda menerima entri asli jika pelanggan tidak merespons perintah.	Dalam kasus ini, pelanggan mungkin telah memasukkan alamat yang tidak ada di sistem, misalnya untuk konstruksi baru.
Berikan masukan	Saat menerbitkan ulang permintaan validasi alamat, Anda juga dapat mengirim permintaan ke endpoint provideValidationFeedback.	Hal ini memberi tahu Google bagaimana Anda pada akhirnya menangani respons akhir. Baca bagian Menangani alamat yang diperbarui.

Coba demonya. Bagian lainnya dalam dokumen ini menggunakan berbagai contoh untuk membantu Anda memahami perbaikan, mengonfirmasi, dan menyetujui proses alur yang dijelaskan di atas. Anda dapat mempelajari hasil dari contoh ini dengan memasukkannya ke dalam demo Address Validation API.

Memperbaiki alamat

Perbaiki alamat jika hasilnya dengan jelas menunjukkan bahwa alamat tersebut tidak dapat dituju. Selanjutnya, sistem Anda dapat meminta pelanggan untuk memberikan informasi yang diperlukan, setelah itu Anda akan menerbitkan ulang alur kerja untuk mendapatkan alamat hasil tujuan.

Catatan: Jika Anda mengulangi permintaan ke Address Validation API untuk alamat yang sama, Anda dapat melakukan panggilan ke provideValidationFeedback untuk menunjukkan hasil. Lihat Menangani Alamat Amerika Serikat.

Perbaiki sinyal

Address Validation API memberikan sejumlah sinyal untuk memberi tahu Anda apakah alamat harus diperbaiki.

1. Perincian validasi dan komponen yang hilang

Kedua sinyal berikut memberikan indikasi terbaik dari alamat yang bermasalah:

• Setiap kali kolom validationGranularity bernilai OTHER, sistem Anda harus menyelidiki sinyal komponen alamat untuk mempelajari lebih lanjut tempat terjadinya error dan cara memperbaikinya.
• Setiap kali objek address yang telah diproses menampilkan kolom missingComponentTypes, sistem Anda harus memeriksa komponen tersebut. Komponen yang hilang juga menyebabkan alamat tidak lengkap dan tidak dapat dikirim.

2. Sinyal lainnya

Address Validation API juga memberikan sinyal lain untuk membantu mendiagnosis masalah tertentu:

Komponen yang mencurigakan	Jika enum tingkat konfirmasi untuk suatu komponen adalah UNCOMFIRMED_AND_SUSPICIOUS, kemungkinan komponen tersebut salah.
Komponen yang belum di-resolve	unresolvedToken adalah bagian dari input yang tidak dikenali sebagai bagian alamat yang valid.

3. Sinyal alamat AS

Kolom tertentu yang hanya berlaku untuk alamat AS memberikan sinyal berguna bahwa alamat tidak dapat dikirimkan dan harus diperbaiki. Untuk alamat yang harus diperbaiki, Anda akan melihat yang berikut:

dpvConfirmation	Berupa N, D, atau kosong.

Untuk mengetahui detail tentang dpvConfirmation, lihat Menangani alamat di Amerika Serikat.

Memperbaiki contoh alamat

Konfirmasi alamat

Anda mengonfirmasi alamat saat verdict menunjukkan bahwa Address Validation API menyimpulkan atau melakukan perubahan pada komponen alamat untuk menghasilkan alamat yang divalidasi. Dalam hal ini, Anda memiliki alamat tujuan, tetapi lebih memilih bahwa alamat yang dihasilkan adalah alamat yang dituju pelanggan.

Untuk memberi pelanggan permintaan yang benar, logika Anda akan mengidentifikasi komponen yang ditandai oleh layanan untuk menentukan tindakan atau tanda mana yang diterapkan API ke komponen, seperti inferred, replaced, atau spellCorrected. Lihat AddressComponent dalam referensi.

Catatan: Pertimbangkan tingkat risiko Anda saat memutuskan apakah akan mengonfirmasi alamat dengan pelanggan atau menerimanya sebagai valid. Selain itu, jika Anda mengirim ulang permintaan ke Address Validation API, Anda dapat melakukan panggilan ke provideValidationFeedback untuk menunjukkan hasil. Baca bagian Menangani alamat terbaru.

Konfirmasi sinyal

Address Validation API memberikan sejumlah sinyal untuk memberi tahu Anda apakah alamat harus dikonfirmasi.

1. Perincian Validasi

validationGranularity 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 tersebut juga memberikan hal berikut untuk menentukan komponen yang harus diselidiki:

Data yang disimpulkan	Jika kolom hasInferredComponents adalah true, Anda tahu bahwa API mengisi informasi yang diperoleh dari komponen alamat lain.
Data yang diganti	Jika kolom hasReplacedComponents adalah true, API akan mengganti data yang dimasukkan dengan data yang dianggap valid untuk membuat alamat tersebut.

3. Sinyal alamat AS

Beberapa 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 dpvConfirmation, lihat Menangani alamat di Amerika Serikat.
Respons alamat	Berisi kolom missingComponentType dengan nilai subpremise. Catatan: jika kolom berisi jenis selain subpremise, tindakan akan termasuk dalam kategori alamat perbaikan. Lihat daftar lengkap jenis alamat dalam dokumentasi Geocoding.

Mengonfirmasi contoh alamat

Terima alamat

Anda menerima alamat saat verdict tersebut memberikan tingkat keyakinan tinggi bahwa alamat tersebut dapat dikirim dan dapat digunakan tanpa interaksi pelanggan lebih lanjut dalam proses downstream.

Terima sinyal

Address Validation API memberikan sejumlah sinyal untuk memberi tahu Anda apakah alamat harus dikonfirmasi.

1. Perincian Validasi

validationGranularity sebesar PREMISE atau lebih dapat diterima, tetapi dalam beberapa kasus, ROUTE masih menunjukkan alamat pengiriman.

2. Sinyal lainnya

Putusan untuk alamat berkualitas tinggi juga harus menampilkan hal berikut:

• Tidak ada data yang diganti. Dalam kasus ini, hasReplacedComponents: FALSE.
• Tidak ada komponen yang disimpulkan. Dalam kasus ini, hasInferredComponents: FALSE.

3. Sinyal alamat AS

Beberapa kolom tertentu yang hanya berlaku untuk alamat di AS menunjukkan alamat berkualitas tinggi sebagai tujuan pengiriman. Untuk alamat AS yang dapat diterima, Anda akan melihat hal berikut:

dpvConfirmation	Y Untuk mengetahui detail tentang dpvConfirmation, lihat Menangani alamat di Amerika Serikat.

Menerima contoh alamat