Adres doğrulama çözümü kılavuzu

Test adımlarına genel bakış sunan akış şeması.

Hedef

Address Validation, çeşitli kullanım alanları için değer sağlar ve test sonuçlarının ham kalitesinin ötesinde, keşfetmenizi önerdiğimiz önemli noktalar vardır. Örneğin: Yer Adı Otomatik Tamamlama ve Haritalar gibi kullanıcı işlemleri akışındaki uyumlu ürünlerin bütünsel görünümü, bölgesel kullanılabilirlik ve kurumsal güven ve güvenilirlik.

Address Validation API'yi değerlendirme aşamasına geldiğinizde, test sürecinizin bir parçası olarak kullanmanızı önerdiğimiz bazı yönergeleri aşağıda bulabilirsiniz.

Bu testin amaçları şunlardır:

  1. Address Validation API'nin kullanım alanınıza uygun olduğunu onaylayın.
  2. Address Validation API'nin çözüm gereksinimlerinizi nasıl karşıladığını doğrulayın. Örneğin:
    • Kaliteli adresleri belirleme
    • Kalitesi düşük girişleri ele almak için uyarıda bulunma
    • Çıkarımlar, değiştirmeler ve yazım düzeltmeleri dahil olmak üzere adres verilerinde düzeltmeler yapma.
    • Kargo için biçimlendirilmiş bir adres sağlama.
    • Eksik veya yanlış alt tesis verileriyle ilgili uyarı (yalnızca ABD).
  3. API'yi uygulayarak ölçülebilir bir avantaj elde edeceğinizden emin olun.

Testinizi yaptıktan sonra yukarıdaki soruları yanıtlayabilir ve API'nin işletmeniz için uygun olup olmadığını belirleyebilirsiniz.

Verilerinizi hazırlama

Testiniz, mevcut adres verilerinizin bir örneği üzerinde gerçekleştirilmelidir. Test için verileri kendiniz seçmeyin. Bunun yerine, faaliyet gösterdiğiniz coğrafi bölgeleri temsil eden rastgele örnekler seçin. Yani hem ABD'de hem de Birleşik Krallık'ta faaliyet gösteriyorsanız ancak işletmenizin% 70'i Birleşik Krallık'ta, %30'u ABD'de yürütülüyorsa örnek bu dağılımı yansıtmalıdır.

Yakalamanın yapıldığı noktadaki adresleri kullanın. Örneğin, e-ticaret ödeme sayfanızda adres doğrulamayı uygulamayı planlıyorsanız Address Validation API'yi uygulayarak değiştirilebilecek mevcut işlemler gerçekleşmeden önce müşterilerinizin forma girdiği adresleri kullanın.

Test için yaklaşık 5.000-10.000 kayıttan oluşan bir örneklem boyutu hazırlayın.

API'yi çağırma

Bölüm ön koşulu: Address Validation isteği gönderme hakkında bilgi sahibi olun.

Verileri hazırladıktan sonra her adres kaydını API'ye karşı çalıştırmanız gerekir.

API'yi nasıl çağıracağınızla ilgili talimatlar için Address Validation API belgelerine bakın. Adresleri yüksek hacimde işlemek için Address Validation API'yi kullanmayla ilgili en iyi uygulamaları açıklayan bir makalemiz de bulunmaktadır.

Bu adımın sonucunda, her adres kaydı için API'den veri çıkışı elde edilmelidir. Ardından, API'nin kullanım alanınıza uygunluğunu belirlemek için sonuçları analiz edebilirsiniz. Bunun için e-tablo, veritabanı veya başka bir araç kullanmak size kalmış.

Sonuçları inceleme

Bölüm ön koşulu: Doğrulama yanıtını nasıl işleyeceğinizi, özellikle de Düzelt, Onayla ve Kabul Et kavramlarını anlayın.

Bu bölümde, çözümün uygunluğunu değerlendirmek için analiz edebileceğiniz çıktı senaryolarını ele alacağız.

Bu belgede ele alınan önemli API alanlarına genel bakış

Yanıt Verileri

Bu nedir?

Değerlendirme

Nasıl yardımcı olur?

verdict.inputGranularity

Adresin giriş ayrıntı düzeyini açıklar.

SUB_PREMISE

PREMISE

PREMISE_PROXIMITY

ENGELLE

ROUTE

OTHER

Giriş adresinin geçerli olabilecek kadar yeterli veriye sahip olup olmadığını belirlemenizi sağlar.

verdict.validationGranularity

Adresin genel çıkış doğrulamasını açıklar.

SUB_PREMISE

PREMISE

PREMISE_PROXIMITY

ENGELLE

ROUTE

OTHER

API'den alınan çıkışta genel adres kalitesini belirlemenizi sağlar.

verdict.hasInferredComponents

API'nin bir bileşeni tahmin edip etmediğini belirtir.

Doğru/Yanlış

API, verileri tahmin edebildiği durumlarda eksik bileşenleri ekleyebilir. Örneğin, eyalet kodu eksik olabilir.

verdict.hasReplacedComponents

API'nin bir bileşeni değiştirip değiştirmediğini belirtir.

Doğru/Yanlış

API, bazı senaryolarda yanlış bileşenleri doğru verilerle değiştirebilir.

verdict.addressComplete

Adresin tam olup olmadığını belirtir.

Doğru/Yanlış

API, çıkış adresinin gerekli tüm bileşenlere sahip olduğunu belirlerse bu değer doğru olur.

address.missingComponentTypes

Adreste eksik bileşenler varsa uyarı sinyali.

Değerler için ikinci tabloya bakın.

Eksik bir adresteki eksik bileşenleri vurgulama

Geçerli adresleri inceleme

Sisteminizin geçerli olarak kabul edeceği adres grubunu belirlemek için API'den döndürülen verileri sıralayın. API'den alınacak önemli sinyaller şunlardır:

  • verdict.validationGranularity, PREMISE veya daha iyi bir değer içeriyor.
  • verdict.addressComplete true.
  • Tahmin edilen veya değiştirilen bileşen yok.

Daha fazla bilgi için Adres kabul etme başlıklı makaleyi inceleyin.

Bu alıştırmanın çıktısı, sisteminiz tarafından geçerli kabul edilecek adres verilerinin bir alt kümesi olmalıdır. Bu aşamada şunları belirleyebilirsiniz:

  • Kabul yüzdesi oranı kabul edilebilir mi?
  • Mevcut bir Address Validation iş akışı kullanıyorsanız kabul oranı eşdeğer mi yoksa daha mı iyi?

Örnek: Geçerli adres

Girilen adres

Bölge

76 Buckingham Palace Road, Londra SW1W 9TQ

Birleşik Krallık

Karar

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "PREMISE",
  "geocodeGranularity": "PREMISE",
  "addressComplete": true
}

Geçersiz adresleri inceleme

Bu adım, geçersiz olarak işaretlenen adres verilerinin bir kısmını manuel olarak inceleme ve Address Validation API'yi kullanmadan bu geçersiz adresin sonraki aşamalarda sorunlara neden olup olmayacağını görme fırsatı sunar.

Sisteminizin geçersiz olarak işaretleyeceği adres grubunu belirlemek için API'den döndürülen verileri sıralayın. API'den alınacak önemli sinyaller şunlardır:

  • verdict.validationGranularity, risk düzeyinize bağlı olarak OTHER veya ROUTE şeklinde ayarlanır.
  • verdict.addressComplete false.

Daha fazla bilgi için Adres düzeltme başlıklı makaleyi inceleyin.

Bu alıştırmanın çıktısı, sisteminiz tarafından geçersiz olarak işaretlenecek adres verilerinin bir alt kümesi olmalıdır. Bu noktada, geçersiz yüzde oranının kabul edilebilir olup olmadığını belirleyebilirsiniz.

Adresleri geçersiz olarak işaretlemenin Address Validation API'nin temel işlevlerinden biri olduğunu ve geçersiz olarak işaretlenen adreslerin oranının yüksek olmasının API'nin performansını olumsuz etkilemediğini unutmayın. API, adreste bir sorun olduğu bilgisini verir. Bu sayede, hataları daha erken yakalayarak iş akışınızda verimlilik sağlayabilir ve daha sonra sorun yaşanmasını önleyebilirsiniz.

Örnek: Geçersiz adres

Girilen adres

Bölge

21 45 40th street

ABD

Karar

{
  "inputGranularity": "PREMISE",
  "validationGranularity": "OTHER",
  "geocodeGranularity": "OTHER",
  "hasUnconfirmedComponents": true
}

Eksik veya onaylanmamış bileşenleri inceleme

Bu aşamada, eksik veya onaylanmamış bileşenler de incelenebilir. Bu, yanıttaki Address nesnesinin bir parçasıdır. Bu iki alan missingComponentTypes ve unconfirmedComponentTypes'dir.

Bir adresin API tarafından neden geçersiz olarak işaretlendiğini tespit etmek ve adres için doğru bilgileri toplamak amacıyla bu alanları kullanın. Bu sayede, yanlış olan belirli alanları veri toplama noktasına geri göndererek adresin geçerli olmasını sağlayabilirsiniz. Bu, API'nin verilerinizin kalitesi hakkında size özel bilgiler vererek değer sağlama yöntemlerinden biridir.

Örnek: Eksik ve onaylanmamış bileşen

Girilen adres

Bölge

Fake St, New York, NY 10011

ABD

Karar

{
     "inputGranularity": "ROUTE",
     "validationGranularity": "OTHER",
     "geocodeGranularity": "OTHER",
     "hasUnconfirmedComponents": true
}

Eksik ve onaylanmamış bileşenler

"missingComponentTypes": [
    "street_number"
],
"unconfirmedComponentTypes": [
    "route"
]

Düzeltme yapılan adresleri inceleme

Address Validation API, giriş verilerinde düzeltmeler yapabilir, geçersiz olabilecek bir adres girişini alıp geçerli adres verileri döndürebilir. API'nin değer katma yollarından biri budur ve test kapsamında bunu yakalamak önemlidir.

Dikkat edilmesi gereken önemli sinyaller şunlardır:

  • inferred, replaced veya spellCorrected, addressComponents öğelerinden herhangi birinde true olarak ayarlanmış.
  • verdict.hasInferredComponents veya verdict.hasReplacedComponents, true olarak ayarlandı.

Daha fazla bilgi için Adres onaylama başlıklı makaleyi inceleyin.

Bu alıştırmanın çıktısı, API tarafından düzeltme uygulanmış adres verilerinin bir alt kümesi olmalıdır.

API'nin, verilerinizde alt akış iş akışınızdaki uyuşmazlığı azaltacak düzeltmeler yapıp yapmadığını belirlemek için bu verilerin bir kısmı manuel olarak incelenebilir.

Örnek: Düzeltme içeren adres

Girilen adres

Bölge

76 Bruckingm Palace Road, Londra SW1W 9TQ

Birleşik Krallık

addressComponent rotası

{
    "componentName": {
        "text": "Buckingham Palace Road",
        "languageCode": "en"
    },
    "componentType": "route",
    "confirmationLevel": "CONFIRMED",
    "spellCorrected": true
}

[Yalnızca ABD] Eksik veya yanlış alt tesis verileri içeren adresi inceleme

Address Validation API, ABD adresleri için alt tesisin eksik veya yanlış olup olmadığını belirleyebilir.

Dikkat edilmesi gereken önemli sinyaller şunlardır:

  • Address nesnesinde:
    • unconfirmedComponentTypes, subpremise değerini içeriyor
    • missingComponentTypes, subpremise değerini içeriyor
  • UspsData nesnesinde:
    • dpvConfirmation, D (alt tesis eksik)
    • dpvConfirmation, S (alt tesis onaylanmadı)

Daha fazla bilgi için ABD adreslerini işleme başlıklı makaleyi inceleyin.

Bu test, verilerinizde eksik veya yanlış alt tesisler (ör. apartman dairesi numaraları) ile ilgili bir sorun olup olmadığını gösterir. Bu durum, özellikle teslimat kullanım durumlarında sorunlara neden olabilir. Address Validation API, bu durumu daha erken tespit ederek iş akışınıza değer katabilir ve düzeltilmiş verileri toplamak için gerekli adımları uygulamanıza olanak tanır.

Örnek: Eksik alt tesis

Girilen adres

Bölge

111 8th Avenue, Manhattan, NY 10011

ABD

Eksik bileşen

"missingComponentTypes": [
    "subpremise"
]

USPS verileri DPV onayı

"dpvConfirmation": "D"

[Yalnızca ABD] USPS standardizedAddress'i inceleme

Address Validation API, ABD adresleri için USPS standartlaştırılmış adresini de döndürür. Bu, özellikle kargo etiketlerinizde USPS biçimli adreslerin yazdırılması gerekiyorsa önemlidir.

Bu verileri görüntülemek ve iş akışınıza değer katıp katmadığını belirlemek için UspsAddress incelenebilir.

Örnek: USPS standartlarına uygun adres

"standardizedAddress": {
    "firstAddressLine": "111 8TH AVE FL 11",
    "cityStateZipAddressLine": "NEW YORK NY 10011-5201",
    "city": "NEW YORK",
    "state": "NY",
    "zipCode": "10011",
    "zipCodeExtension": "5201"
}

Sonuç

Test etmeye başlayın: Doğru adres verileri elde etmek, müşteri deneyimini iyileştirmek ve işletme operasyonlarınızı kolaylaştırmak için Address Validation API'yi test etmeye hemen başlayın. Yukarıda açıklanan test senaryolarını uyguladıktan sonra Address Validation API'nin iş akışınıza değer katıp katmayacağını belirlemek için ihtiyacınız olan bilgilere sahip olursunuz.

Önerilen ek kaynaklar:

Katkıda bulunanlar

Henrik Valve | DevX Mühendisi