Membuat logika validasi

Dokumen ini menjelaskan proses untuk membuat sistem pemeriksaan alamat guna menangani berbagai respons dari Address Validation API. Dokumen ini membahas cara membuat logika untuk menggunakan respons dengan benar, menyelidiki sinyal lain dari API, serta kapan dan bagaimana cara meminta informasi lebih lanjut dari pelanggan.

Secara umum, respons API menentukan cara sistem Anda menangani alamat sebagai berikut:

• Perbaiki—alamatnya berkualitas rendah. Anda harus meminta informasi lebih lanjut.
• Konfirmasi—alamatnya berkualitas tinggi, tetapi memiliki perubahan dari alamat input. Anda mungkin akan meminta konfirmasi.
• Terima—alamatnya berkualitas tinggi. Anda dapat menerima alamat yang diberikan.

Tujuan utama

Dokumen ini membantu Anda mengubah sistem untuk menganalisis respons API dengan sebaik-baiknya dan menentukan tindakan berikutnya yang akan diambil dengan alamat yang diberikan. Pseudocode berikut menggambarkan 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 mengetahui detail selengkapnya. Anda juga dapat menggunakan implementasi open source logika ini, yang ada di Extended Component Library.

Ringkasan alur kerja

Tabel di bawah 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 akan 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 verdict menunjukkan informasi penting yang tidak ada dan harus diberikan. Alamat yang ditampilkan oleh API mungkin tidak berkualitas untuk pengiriman. Alur kerja Selidiki komponen alamat jika perlu. Minta pelanggan untuk memperbaiki masalah alamat. Minta validasi untuk alamat yang diperbarui. Lanjutkan dengan alamat. Sinyal verdict Salah satu hal berikut berlaku: validationGranularity ditetapkan ke OTHER. addressComplete adalah false.
Konfirmasi alamat	Respons dari verdict menunjukkan alamat yang dapat dikirim tetapi telah melakukan perubahan pada input asli: menyimpulkan data yang dikoreksi ejaannya, atau data yang dapat dikonfirmasi. Alur kerja Koreksi diperlukan: Selidiki komponen alamat jika perlu. Minta validasi untuk alamat yang diperbarui. Lanjutkan dengan alamat. Tidak ada koreksi yang diperlukan: Lanjutkan dengan alamat. Sinyal verdict Semua hal berikut berlaku: validationGranularity berisi ROUTE addressComplete adalah true. hasInferredComponents kolom adalah true ATAU hasReplacedComponents kolom adalah true.
Terima alamat	Respons Address Validation API menunjukkan alamat berkualitas sangat baik. Alur kerja Lanjutkan dengan alamat yang ditampilkan. Sinyal verdict Semua hal berikut berlaku: validationGranularity berisi PREMISE atau yang lebih baik. addressComplete adalah true. Tidak ada komponen yang disimpulkan atau diganti.

Panduan implementasi

Saat mendesain cara sistem Anda merespons sinyal validasi alamat, rekomendasi berikut dapat membantu Anda membuat model respons yang lebih efektif. Namun, ini hanya rekomendasi, jadi perlu diingat bahwa implementasi Anda harus sesuai dengan model bisnis Anda.

	Panduan	Detail
Tingkat risiko	Pertimbangkan tingkat toleransi untuk situasi Anda saat menyeimbangkan antara meminta koreksi dan menerima alamat seperti yang dimasukkan.	Address Validation API menampilkan berbagai sinyal yang dapat Anda gabungkan dengan tingkat risiko untuk mengoptimalkan proses validasi Misalnya, jika alamat memiliki nomor jalan yang belum dikonfirmasi, Anda dapat tetap menerimanya. Di sisi lain, jika operasi bisnis Anda memerlukan presisi alamat yang lebih tinggi, Anda dapat meminta pengguna. Untuk contoh yang dapat masuk ke salah satu kategori, lihat Nomor jalan yang belum dikonfirmasi di luar AS di Terima alamat - 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 dalam sistem, seperti untuk konstruksi baru.

Coba demo. Bagian lain dari dokumen ini menggunakan berbagai contoh untuk membantu Anda memahami proses alur perbaikan, konfirmasi, dan penerimaan yang dijelaskan di atas. Anda dapat menjelajahi hasil dari contoh ini dengan memasukkannya ke dalam demo Address Validation di Maps JavaScript API.

Memperbaiki alamat

Perbaiki alamat jika hasilnya menunjukkan dengan jelas bahwa alamat tersebut tidak dapat dikirim. Sistem Anda kemudian dapat meminta pelanggan untuk memberikan informasi yang diperlukan, setelah itu Anda menerbitkan ulang alur kerja untuk mendapatkan alamat yang dapat dikirim.

Sinyal perbaikan

Address Validation API menyediakan sejumlah sinyal untuk memberi tahu Anda jika alamat harus diperbaiki.

1. Granularitas validasi dan komponen yang tidak ada

Dua sinyal ini memberikan indikasi terbaik alamat yang bermasalah:

• Setiap kali validationGranularity kolom adalah OTHER, sistem Anda harus menyelidiki sinyal komponen alamat untuk mempelajari lebih lanjut tempat terjadinya error dan cara memperbaikinya.
• Setiap kali objek address yang diproses pasca-proses menampilkan kolom missingComponentTypes, sistem Anda harus memeriksa komponen tersebut. Komponen yang tidak ada juga membuat alamat tidak lengkap dan tidak dapat dikirim.

2. Sinyal lainnya

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

Komponen mencurigakan	Jika enum tingkat konfirmasi untuk komponen adalah UNCOMFIRMED_AND_SUSPICIOUS, kemungkinan komponen tersebut salah.
Komponen yang tidak dapat diselesaikan	An 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 yang berguna bahwa alamat tersebut tidak dapat dikirim dan harus diperbaiki. Untuk alamat yang perlu diperbaiki, Anda akan melihat hal berikut:

dpvConfirmation	N, D, atau kosong.

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

Contoh perbaikan alamat

Mengonfirmasi alamat

Anda mengonfirmasi alamat jika verdict menunjukkan bahwa Address Validation API menyimpulkan atau membuat perubahan pada komponen alamat untuk menghasilkan alamat yang divalidasi. Dalam kasus ini, Anda memiliki alamat yang dapat dikirim, tetapi lebih memilih keyakinan yang lebih besar bahwa alamat yang dihasilkan adalah alamat yang diinginkan oleh pelanggan.

Untuk memberikan perintah yang benar kepada pelanggan, logika Anda akan mengidentifikasi komponen yang ditandai oleh layanan untuk menentukan tindakan atau tanda 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.

Sinyal konfirmasi

Address Validation API menyediakan sejumlah sinyal untuk memberi tahu Anda jika alamat harus dikonfirmasi.

1. Granularitas Validasi

A validationGranularity dari ROUTE atau yang lebih baik dapat diterima, tetapi baik 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 akan diselidiki:

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

3. Sinyal alamat AS

Kolom tertentu yang hanya berlaku untuk alamat 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 Amerika Serikat.
Respons alamat	Berisi kolom missingComponentTypes dengan nilai subpremise. Catatan: jika kolom berisi jenis selain subpremise, tindakan tersebut akan masuk ke kategori perbaikan alamat. Lihat daftar lengkap jenis alamat dalam dokumentasi Geocoding.

Contoh konfirmasi alamat

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.

Sinyal penerimaan

Address Validation API menyediakan sejumlah sinyal untuk memberi tahu Anda jika alamat harus dikonfirmasi.

1. Granularitas Validasi

validationGranularity dari PREMISE atau yang lebih baik dapat diterima, tetapi dalam beberapa kasus, ROUTE masih menunjukkan alamat yang dapat dikirim.

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 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 dpvConfirmation, lihat Menangani alamat Amerika Serikat.

Contoh penerimaan alamat