Temel adres doğrulama yanıtını anlama

Address Validation API, iki üst düzey özellik içeren JSON nesnesi olarak bir yanıt gövdesi sağlar:

{
  "result": {
    // Validation verdict.
    "verdict": {},
    // Address details determined by the API.
    "address": {},
    // The geocode generated for the input address.
    "geocode": {},
    // Information indicating if the address is a business, residence, etc.
    "metadata": {},
    // Information about the address from the US Postal Service
    // ("US" and "PR" addresses only).
    "uspsData": {},
  },
  // A unique identifier generated for every request to the API.
  "responseId": "ID"
}

Bu dokümanda result nesnesine odaklanılıyor. responseID hakkında bilgi edinmek için Güncellenen adresleri işleme bölümüne göz atın.

verdict özelliği

verdict özelliği, adres doğrulama sonuçlarını özetler ve adres kontrolü mantığı oluştururken değerlendirilecek ilk özellik olmalıdır. Özellik, çıkış adresinin kalitesine bağlı olarak çeşitli alanlar döndürebilir. Örneğin, aşağıda yüksek kalitede bir adresin verdict özelliği gösterilmektedir. Bu özellik, söz konusu istek için 4 alan döndürür:

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

Aşağıdaki bölümlerde verdict özelliğindeki tüm alanlar özetlenmektedir.

Referans kılavuzunda Karar bölümüne bakın.

Adresin ayrıntı düzeyi

Adres ayrıntı düzeyi, bir adresin veya coğrafi kodun belirliliğini belirlemede kullanılan ayrıntı düzeyini ifade eder. validationGranularity yanıtındaki adres belirginliği, bir adresin teslim edilebilir olup olmadığına dair önemli bir sinyaldir.

verdict özelliği, şu ayrıntı düzeyi sinyallerini döndürür:

  • inputGranularity: Address Validation API'ye gönderilen adresten yakalanan ayrıntı düzeyini açıklar. İstekteki adres ayrıntısı düzeyi, doğrulama yanıtındaki adres ayrıntısı düzeyini etkiler. Örneğin, inputGranularity değeri PREMISE altında olan bir adres genellikle validationGranularity seviyesinin PREMISE seviyesine çıkmaz.
  • validationGranularity: Address Validation API'nin adresi tam olarak doğrulayabileceği ayrıntı düzeyi. Çoğu durumda PREMISE veya SUB_PREMISE ayrıntı düzeyi, teslimat olasılığı yüksek bir kalite adresine işaret eder.
  • geocodeGranularity: Adresle ilişkilendirilen coğrafi kodun ayrıntı düzeyini açıklar. Örneğin, Google kayıtları bir apartmanın numarasını gösterebilir, ancak büyük bir apartman kompleksi içindeki belirli bir dairenin kesin konumunu belirtmeyebilir. Bu durumda, validationGranularity SUB_PREMISE ancak geocodeGranularityisPREMISE` olur.
Referans kılavuzunda Ayrıntı düzeyi bölümüne bakın.

Adresin tamlığı

Sonuç, addressComplete özelliğini yüksek kaliteli bir adres için sinyal olarak döndürür. Bu, özellikle eksik, çözümlenmemiş veya beklenmeyen bileşenleri olmadığı anlamına gelir:

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

Adreste eksik, çözülmemiş veya beklenmeyen bileşenler varsa alan false olarak ayarlanır.

Referans kılavuzundaki Karar ve Adres bölümünde addressComplete bölümüne bakın.

Adres kalitesi

Olası alanlar, adres bileşenleriyle ilgili sorunları veya tahmin edilen ya da eksik adres bileşenleri gibi düzeltme işlemlerini belirtir. Örneğin, aşağıdaki verdict özelliği, onaylanmamış bileşenlere sahip ve addressComplete alanı eksik bir adresi belirtir:

"verdict": {
    "inputGranularity": "PREMISE",
    "validationGranularity": "OTHER",
    "geocodeGranularity": "OTHER",
    "hasUnconfirmedComponents": true,
    "hasInferredComponents": true
}
Referans kılavuzunda Karar bölümüne bakın.

address ve addressComponent özellikleri

address özelliği, istekte sağlanan işlenmiş adres için biçimlendirmenin yanı sıra adresin yanlış yazılmış kısımları, değiştirilen yanlış bölümler ve tahmin edilen eksik parçalar dahil olmak üzere adresin bileşen düzeyinde özetlerini sağlar.

Referans kılavuzunda Address başlığına göz atın.

addressComponent özelliği, Address Validation API'nin işlediği adresin öğelerinin veya bileşenlerinin ayrıntılı bir listesini sağlayan address alt bileşenidir. API; her bileşen alanını adına, türüne ve onay düzeyine göre tanımlar.

Referans kılavuzunda addressComponent başlığına göz atın.

geocode özelliği

geocode özelliği, giriş adresiyle ilişkili coğrafi coğrafi konumu belirtir. Bu tesis, konumun kendisiyle ilgili bilgiler (ör. yer kimliği) sağlar.

Referans kılavuzunda Geocode başlığına göz atın.

metadata özelliği

Bu özellik, Address Validation API tarafından işlenen her adres için doldurulmayabilir ancak adresin konut, iş veya posta kutusu türünde olduğunu belirtir.

Address Validation API kapsamı'na ve Address metadata referansına göz atın.

uspsData özelliği

Bu tesis, ABD posta adresleri için yararlı bilgiler sağlar. Ancak hizmet tarafından doğrulanan her adres için bu bilgilerin tamamen doldurulacağı garanti edilmez. Bu nedenle, adresleri doğrulamak için tek aracı olarak bu özelliği kullanmamalısınız. Bunun yerine verdict ve address değerlerini de kontrol edin.

ABD'deki adresleri işleme bölümüne ve UspsData referansına göz atın.