Bu belgede, Adres Doğrulama API'sinden gelen çeşitli yanıtları işlemek için bir adres kontrol sistemi oluşturma süreci açıklanmaktadır. Yanıtı doğru şekilde kullanmak, API'den gelen diğer sinyalleri incelemek ve müşterilerinizden daha fazla bilgi istemek için mantığınızı nasıl oluşturacağınız açıklanır.
Genel olarak API yanıtı, sisteminizin bir adresi aşağıdaki şekillerde işlemesi gerektiğini belirler:
- Düzeltin: Adresin kalitesi düşük. Daha fazla bilgi istemelisiniz.
- Onayla: Adres yüksek kaliteli ancak giriş adresinden farklı. Onay istenebilir.
- Kabul et: Adres yüksek kalitelidir. Sağlanan adresi kabul edebilirsiniz.
Temel amaç
Bu belge, sisteminizi API yanıtını en iyi şekilde analiz edecek ve sağlanan adreslerle ilgili sonraki işlemleri belirleyecek şekilde değiştirmenize yardımcı olur. Aşağıdaki sözde kodda olası bir akış gösterilmektedir.
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.
Tam olarak hangi mantığın kullanılacağı durumunuza bağlıdır. Daha fazla bilgi için Uygulama rehberi'ne bakın. Bu mantığın açık kaynaklı uygulamamızı da kullanabilirsiniz. Bu uygulama, Genişletilmiş Bileşen Kitaplığı'nda yer alır.
İş akışına genel bakış
Aşağıdaki tabloda, sisteminizle ilgili iki işlem özetlenmektedir:
- Düzeltme, onaylama ve kabul etme davranışına göre kullanılacak iş akışı.
- Yanıttan kontrol edilecek ilk sinyaller. Burada açıklanan sinyaller
verdictmülkünden gelir ve kontrol edilecek tek sinyaller değildir ancak adres kalitesiyle ilgili ilk göstergeyi sağlar. Her davranış türü, bu belgedeki incelemeniz gerekebilecek diğer sinyalleri açıklayan bir bölüme karşılık gelir.
| Sistem davranışınız | |||
|---|---|---|---|
| Adresi düzeltin. |
|
||
| Adresi onaylayın. |
|
||
| Adresi kabul et |
Address Validation API yanıtı, adresin mükemmel kalitede olduğunu gösterir.
|
||
Uygulama kılavuzu
Sisteminizin adres doğrulama sinyallerine nasıl yanıt vereceğini tasarlarken aşağıdaki öneriler daha etkili bir yanıt modeli oluşturmanıza yardımcı olabilir. Ancak bunlar yalnızca öneri olduğundan uygulamanızın iş modelinize uygun olması gerektiğini unutmayın.
| Yönergeler | Ayrıntılar | |
|---|---|---|
| Risk düzeyi |
Düzeltme isteme ve girilen adresi kabul etme arasında denge kurarken durumunuzla ilgili tolerans seviyesini göz önünde bulundurun. |
Adres Doğrulama API'si, doğrulama sürecinizi optimize etmek için risk düzeyinize dahil edebileceğiniz çeşitli sinyaller döndürür. Örneğin, bir adresin onaylanmamış bir sokak numarası varsa yine de kabul edebilirsiniz. Öte yandan, işletme faaliyetiniz daha fazla adres hassasiyeti gerektiriyorsa kullanıcınızdan bunu yapmasını isteyebilirsiniz. Her iki kategoriye de girebilecek bir örnek için Adresi kabul etme - örnekler bölümündeki ABD dışı onaylanmamış sokak numarası'na bakın. |
| Adresleri kabul etme |
Müşteri istemlere yanıt vermezse sisteminizin orijinal girişi kabul etmesine izin vermek iyi bir uygulamadır. |
Bu gibi durumlarda müşteri, sistemde olmayan bir adres (ör. yeni bir inşaat) girmiş olabilir. |
Adres düzeltme
Sonuçlar, adresin teslim edilemeyeceğini açıkça gösterdiğinde adresi düzeltin. Sisteminiz daha sonra müşteriden gerekli bilgileri sağlamasını isteyebilir. Bu bilgileri aldıktan sonra, teslimat adresi almak için iş akışınızı yeniden yayınlarsınız.
Sinyalleri düzeltme
Adres Doğrulama API'si, bir adresin düzeltilip düzeltilmemesi gerektiğini anlamanız için çeşitli sinyaller sağlar.
1. Doğrulama ayrıntı düzeyi ve eksik bileşenler
Bu iki sinyal, sorunlu bir adresin en iyi göstergesidir:
validationGranularityalanı her zamanOTHERolduğunda sisteminiz, hatanın nerede oluştuğu ve nasıl düzeltileceği hakkında daha fazla bilgi edinmek için adres bileşeni sinyallerini incelemelidir.- İşlem sonrası
addressnesnesi hermissingComponentTypesalanı döndürdüğünde sisteminiz bu bileşeni kontrol etmelidir. Eksik bileşenler de adresi eksik ve teslim edilemez hale getirir.
2. Diğer sinyaller
Adres Doğrulama API'si, belirli sorunların teşhis edilmesine yardımcı olmak için diğer sinyalleri de sağlar:
| Şüpheli bileşenler | Bir bileşenin onay düzeyi numaralandırması UNCOMFIRMED_AND_SUSPICIOUS olduğunda bileşen büyük olasılıkla yanlıştır.
|
|---|---|
| Çözümlenmemiş bileşen | unresolvedToken, girişin geçerli bir adres bölümü olarak tanınmayan kısmıdır. |
3. ABD adres sinyalleri
Yalnızca ABD adresleri için geçerli olan belirli alanlar, adresin teslim edilemediği ve düzeltilmesi gerektiği konusunda faydalı bir sinyal sağlar. Düzeltilmesi gereken bir adres için şunları görürsünüz:
dpvConfirmation
|
N, D veya boş olmalıdır.
|
|---|
dpvConfirmation ile ilgili ayrıntılar için ABD adreslerini işleme başlıklı makaleyi inceleyin.
Adresi onaylama
Karar, Adres Doğrulama API'sinin doğrulanmış bir adres oluşturmak için adres bileşenlerini tahmin ettiğini veya bu bileşenlerde değişiklik yaptığını gösterdiğinde adresi onaylarsınız. Bu gibi durumlarda, teslim edilebilir bir adresiniz vardır ancak sonuçtaki adresin müşteri tarafından amaçlanan adres olduğundan daha fazla emin olmak istersiniz.
Müşteriye doğru istemi sağlamak için mantığınız, hizmet tarafından işaretlenen bileşenleri tanımlayarak API'nin bileşene hangi işlemi veya işareti uyguladığını belirler (ör. inferred, replaced veya spellCorrected).
Referanstaki AddressComponent'a bakın.
Onay sinyalleri
Adres Doğrulama API'si, bir adresin onaylanıp onaylanmaması gerektiğini anlamanız için çeşitli sinyaller sağlar.
1. Doğrulama Ayrıntı Düzeyi
ROUTE veya daha iyi bir validationGranularity kabul edilebilir ancak PREMISE veya SUBPREMISE
teslim edilebilirlik açısından daha güçlü bir sinyal sağlar.
2. Diğer sinyaller
Adres girişini müşteriyle onaylamaya karar verirken karar, hangi bileşenlerin inceleneceğini belirlemek için aşağıdakileri de sağlar:
| Tahmin edilen veriler |
hasInferredComponents alanı true olduğunda API'nin, diğer adres bileşenlerinden elde ettiği bilgileri doldurduğunu anlarsınız.
|
|---|---|
| Değiştirilen veriler |
hasReplacedComponents alanı true olduğunda API, girilen verileri adresi geçerli kılmak için uygun gördüğü verilerle değiştiriyordu.
|
3. ABD adres sinyalleri
Yalnızca ABD adresleri için geçerli olan belirli alanlar, mantığınızın müşteriden ayrıntıları onaylaması gerektiğini gösterir. Aşağıdakilerden biri geçerlidir:
dpvConfirmation
|
S
|
|---|---|
| Adres yanıtı | missingComponentTypes alanını subpremise değeriyle içeriyor.
|
Adresi kabul etme
Karar, adresin teslim edilebilir olduğuna ve sonraki süreçte başka müşteri etkileşimi olmadan kullanılabileceğine dair yüksek düzeyde güven sağladığında adresi kabul edersiniz.
Sinyalleri kabul etme
Adres Doğrulama API'si, bir adresin onaylanıp onaylanmaması gerektiğini anlamanız için çeşitli sinyaller sağlar.
1. Doğrulama Ayrıntı Düzeyi
PREMISE veya daha iyi bir validationGranularity kabul edilebilir ancak bazı durumlarda ROUTE yine de teslim edilebilir bir adresi gösterir.
2. Diğer sinyaller
Yüksek kaliteli bir adresle ilgili kararda aşağıdakiler de yer almalıdır:
- Değiştirilen veri yok. Bu durumda,
hasReplacedComponents: FALSE. - Çıkarılan bileşen yok. Bu durumda,
hasInferredComponents: FALSE.
3. ABD adres sinyalleri
Yalnızca ABD adresleri için geçerli olan belirli alanlar, teslim edilebilecek yüksek kaliteli bir adresi gösterir. Kabul edilebilir bir ABD adresi için aşağıdakileri görmeniz gerekir:
dpvConfirmation
|
Y
|
|---|