Doğrulama mantığınızı oluşturun

Bu dokümanda, Address Validation API'den gelen çeşitli yanıtları işlemek için bir adres kontrol sistemi oluşturma süreci açıklanmaktadır. Bu makalede, yanıtı doğru şekilde kullanmak, API'den gelen diğer sinyalleri incelemek ve müşterilerinizden ne zaman ve nasıl daha fazla bilgi isteğinde bulunmak için mantığınızı nasıl oluşturacağınız ele alınmaktadır.

API yanıtı, genel olarak sisteminizin bir adresi işleme şeklini belirler:

  • Düzeltme: Adresin kalitesi düşük. Daha fazla bilgi isteyebilirsiniz.
  • Onayla: Adres yüksek kalitelidir ancak giriş adresinden farklıdır. Onay isteyebilirsiniz.
  • Kabul et: Adres yüksek kalitelidir. Sağlanan adresi kabul edebilirsiniz.

Temel amaç

Bu doküman, API yanıtını en iyi şekilde analiz etmek ve sağlanan adreslerle yapılacak sonraki işlemleri belirlemek için sisteminizi değiştirmenize yardımcı olur. Aşağıdaki sözde kod, olası bir akışı göstermektedir.

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 mantık durumunuza bağlıdır. Daha fazla bilgi için Uygulama kılavuzu bölümüne bakın. Bu mantığın Genişletilmiş Bileşen Kitaplığı'ndaki açık kaynak uygulamasını da kullanabilirsiniz.

İş akışına genel bakış

Aşağıdaki tabloda, sisteminizle ilgili iki işlem özetlenmiştir:

  1. Düzeltme, onaylama ve kabul etme davranışına göre kullanılacak iş akışı.
  2. Yanıtta kontrol edilecek ilk sinyaller. Burada açıklanan sinyaller verdict mülkünden gelir ve kontrol edilmesi gereken tek sinyaller değildir ancak adres kalitesinin ilk göstergesini sağlar. Her davranış türü, bu belgedeki bir bölüme karşılık gelir. Bu bölümlerde, incelemeniz gerekebilecek diğer sinyaller açıklanır.
Sistem davranışınız
Adresi düzeltin

verdict tarafından gönderilen yanıtta, sağlanması gereken önemli bilgiler eksik. Address Validation API tarafından döndürülen adres, posta gönderimi için uygun kalitede olmayabilir.

İş akışı

  1. Gerekirse adres bileşenlerini inceleyin.
  2. Müşteriden adres sorunlarını düzeltmesini isteyin.
  3. Güncellenen adresin doğrulanmasını isteyin.
  4. (İsteğe bağlı) API'nin geri bildirim uç noktasına istek gönderin. Güncellenen adresleri işleme bölümüne bakın.
  5. Adrese devam edin.

Sonuç sinyalleri

Aşağıdakilerden herhangi biri geçerliyse:
Adresi onaylama

verdict kaynağından gelen yanıt, teslim edilebilir bir adresi belirtiyor ancak orijinal girişte değişiklikler yapılmış: Yazım düzeltmesi yapılmış veya onaylanabilir veriler olduğu sonucuna varılır.

İş akışı

  1. Düzeltilmesi gerekenler:
    1. Gerekirse adres bileşenlerini inceleyin.
    2. Güncellenen adresin doğrulanmasını isteyin.
    3. (İsteğe bağlı) API'nin geri bildirim uç noktasına istek gönderin. Güncellenen adresleri işleme bölümüne bakın.
    4. Adrese devam edin.
  2. Düzeltme gerekmez:
    1. (İsteğe bağlı) API'nin geri bildirim uç noktasına istek gönderin. Güncellenen adresleri işleme bölümüne bakın.
    2. Adrese devam edin.

Sonuç sinyalleri

Aşağıdakilerin tümü geçerlidir:

  • validationGranularity, ROUTE veya daha iyi bir sürüm içeriyor. Ayrıntı düzeyi değerlerine bakın.
  • addressComplete true.
  • hasInferredComponents alanı true ise VEYA hasReplacedComponents alanı true ise.
Adresi kabul et

Address Validation API yanıtı, mükemmel kalitede bir adres olduğunu gösterir.

İş akışı

İade adresine gidin.

Sonuç sinyalleri

Aşağıdakilerin tümü geçerlidir:

  • validationGranularity, PREMISE veya daha iyi bir sürüm içermelidir. Ayrıntı düzeyi değerlerine bakın.
  • addressComplete true.
  • Tahmine dayalı veya değiştirilmiş bileşen yok.

Uygulama kılavuzu

Sisteminizin Address Validation API'den gelen sinyallere 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 önerilerdir. Bu nedenle, uygulamanızın işletme modelinize uygun olması gerektiğini unutmayın.

Yönergeler Ayrıntılar
Risk düzeyi

Düzeltme isteğinde bulunma ve adresi girildiği şekilde kabul etme arasında denge kurarken durumunuza göre tolerans düzeyini göz önünde bulundurun.

Address Validation API, doğrulama sürecinizi optimize etmek için risk düzeyinizle birlikte kullanabileceğiniz çeşitli sinyaller döndürür.

Örneğin, bir adresin sokak numarası onaylanmamış olsa bile adresi kabul edebilirsiniz. Öte yandan, işletmenizin işleyişi için daha yüksek adres doğruluğu gerekiyorsa kullanıcınızdan adres isteyebilirsiniz. Her iki kategoriye de girebilecek bir örnek için Adres kabul etme - örnekler bölümündeki ABD dışındaki onaylanmamış sokak numarası bölümüne 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 bulunmayan bir adres (ör. yeni inşa edilmiş bir bina) girmiş olabilir.
Geri bildirim sağlama

Adres doğrulama isteğini yeniden gönderirken provideValidationFeedback uç noktasına da istek gönderebilirsiniz.

Bu sayede Google, nihai yanıtı nasıl ele aldığınızı öğrenebilir. Güncellenen adresleri işleme bölümüne bakın.

Adres düzeltme

Sonuçlar, adresin teslim edilemediğini açıkça gösterdiğinde adresi düzeltin. Sisteminiz daha sonra müşteriden gerekli bilgileri vermesini isteyebilir. Ardından, teslimat adresi almak için iş akışınızı yeniden gönderirsiniz.

Sinyalleri düzeltme

Address Validation API, bir adresin düzeltilmesi gerekip gerekmediğini bildirmek için çeşitli sinyaller sağlar.

1. Doğrulama ayrıntı düzeyi ve eksik bileşenler

Sorunlu bir adresin en iyi göstergesi şu iki sinyaldir:

  • validationGranularity alanı OTHER olduğ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.
  • Son işleme tabi tutulan address nesnesi her missingComponentTypes alanı döndürdüğünde sisteminiz bu bileşeni kontrol etmelidir. Eksik bileşenler, adresin eksik ve teslim edilemez olmasına da neden olur.

2. Diğer sinyaller

Address Validation API, belirli sorunları teşhis etmeye yardımcı olacak diğer sinyalleri de sağlar:

Şüpheli bileşenler Bir bileşenin onay düzeyi enum değeri UNCOMFIRMED_AND_SUSPICIOUS ise bileşenin yanlış olması muhtemeldir.
Çözümlenmemiş bileşen unresolvedToken, girişin geçerli bir adres parçası olarak tanınmayan bir parçasıdır.

3. ABD adres sinyalleri

Yalnızca ABD adresleri için geçerli olan belirli alanlar, adresin teslim edilemediğinin ve düzeltilmesi gerektiğinin yararlı bir sinyalini sağlar. Düzeltilmesi gereken bir adres için aşağıdakileri görürsünüz:

dpvConfirmation N, D veya boş.

dpvConfirmation hakkında ayrıntılı bilgi için ABD adreslerini işleme başlıklı makaleyi inceleyin.

Adres örneklerini düzeltme

Adresi onaylama

Adres Doğrulama API'sinin doğrulanmış bir adres oluşturmak için adres bileşenlerinde çıkarım yaptığını veya değişiklik yaptığını belirten bir karar olduğunda bir adresi onaylarsınız. Bu gibi durumlarda, teslim edilebilir bir adresiniz vardır ancak elde edilen adresin müşterinin istediği adres olduğundan emin olmak istersiniz.

Müşteriye doğru istemi sunmak için mantığınız, API'nin bileşene uyguladığı işlemi veya işareti (ör. inferred, replaced veya spellCorrected) belirlemek üzere hizmet tarafından işaretlenen bileşenleri tanımlar. Referanstaki AddressComponent bölümüne bakın.

Sinyalleri onaylama

Address Validation API, bir adresin onaylanıp onaylanmaması gerektiğini bildirmek için çeşitli sinyaller sağlar.

1. Doğrulama Ayrıntı Düzeyi

ROUTE veya daha iyi bir validationGranularity kabul edilir ancak PREMISE veya SUBPREMISE, yayınlama durumuyla ilgili daha güçlü bir sinyal sağlar.

2. Diğer sinyaller

Adres girişini müşteriyle onaylamaya karar verirken, hangi bileşenlerin inceleneceğini belirlemek için kararda aşağıdakiler de sağlanır:

Tahmine dayalı veriler hasInferredComponents alanı true olduğunda, API'nin diğer adres bileşenlerinden edindiği bilgileri doldurduğunu bilirsiniz.
Değiştirilen veriler hasReplacedComponents alanı true olduğunda API, girilen verileri adresi geçerli kıldığını düşündüğü verilerle değiştirdi.

3. ABD adres sinyalleri

Yalnızca ABD adresleri için geçerli olan belirli alanlar, mantığınızın ayrıntıları müşteriyle onaylamasını belirtir. Aşağıdakilerden biri geçerlidir:

dpvConfirmation S

dpvConfirmation hakkında ayrıntılı bilgi için ABD adreslerini işleme başlıklı makaleyi inceleyin.
Adres yanıtı subpremise değerini içeren missingComponentType alanı içerir.

Adres onaylama örnekleri

Adresi kabul etme

Karar, adresin teslim edilebilir olduğuna ve aşağı akış sürecinde başka müşteri etkileşimi olmadan kullanılabileceğine dair yüksek düzeyde güven sağladığında bir adresi kabul edersiniz.

Sinyalleri kabul etme

Address Validation API, bir adresin onaylanıp onaylanmaması gerektiğini bildirmek için çeşitli sinyaller sağlar.

1. Doğrulama Ayrıntı Düzeyi

PREMISE veya daha iyi bir validationGranularity kabul edilir 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 sağlanmalıdır:

  • Değiştirilmiş veri yok. Bu durumda hasReplacedComponents: FALSE.
  • Tahmine dayalı bileşen yok. Bu durumda hasInferredComponents: FALSE.

3. ABD adres sinyalleri

Yalnızca ABD adresleri için geçerli olan belirli alanlar, teslimat yapılabilen yüksek kaliteli bir adresi gösterir. Kabul edilen bir ABD adresi için aşağıdakileri görmeniz gerekir:

dpvConfirmation Y

dpvConfirmation hakkında ayrıntılı bilgi için ABD adreslerini işleme başlıklı makaleyi inceleyin.

Kabul edilen adres örnekleri

Önceki
Temel yanıtı anlama