Google Haritalar Platformu'nu kullanarak konum doğrulama özelliği geliştirme

Hedef

Genellikle bir yerin konumunu doğrulamanız gerekir. Google Haritalar Platformu'nda bu kullanım alanında size yardımcı olabilecek birkaç farklı hizmet vardır. Bu doküman, iki birincil konum doğrulama hizmeti (Address Validation API ve Geocoding API) arasında seçim yapmanıza yardımcı olur.

Address Validation API, müşterilerin bir adresin doğru olup olmadığını onaylamalarına yardımcı olan bir Google Haritalar Platformu teklifidir.

Coğrafi Kodlama API'si ile coğrafi kodlama, adresleri coğrafi koordinatlara dönüştürme işlemidir. Bu koordinatları, işaretçileri bir haritaya veya haritadaki bir konuma yerleştirmek için kullanabilirsiniz.

Adres Doğrulama ve Coğrafi Kodlama API'si arasındaki farklara genel bir bakışı burada bulabilirsiniz.

Şimdi deneyin: Google Cloud Console'u ziyaret edip Address Validation API ile Places API'yi etkinleştirin.

Hangi durumlarda Address Validation API'yi, hangi durumlarda Geocoding API'yi kullanmalısınız?

Yukarıdaki akış şemasıyla ilgili notlar:

• Kullanıcı etkileşimi kullanım alanı, bir kullanıcının sonuçlarla etkileşime geçeceği durumları ifade eder.
• Places Autocomplete bir JavaScript API'si olduğundan kullanıcı arayüzleriyle entegrasyon için uygundur.
• Mevcut adreslerinizdeki veri kalitesi sorunlarının farkında olabilirsiniz. Bu nedenle yalnızca coğrafi kodlar isteseniz de veri kümelerini düzeltmek için bu konumları Address Validation API aracılığıyla çalıştırmanız önerilir.

Yukarıdaki karar ağacına göre bir ürünü diğerine tercih edebileceğiniz birçok durum vardır. Ancak hedeflerinize ulaşmak için her iki ürünü de kullanmanız gerekebilecek başka durumlar da vardır.

Aşağıdaki durumlarda Geocoding API yerine Address Validation API'yi kullanmayı tercih edebilirsiniz:

• Şüpheli veri olma olasılığı yüksektir veya yanlış adres alınmasının olumsuz bir etkisi olabilir. Bunun nedeni, Address Validation API'nin bir girişin neden yüksek hassasiyetli sonuç almadığına dair daha fazla geri bildirim sağlamasıdır.
• Kullanıcı girişlerini (ör.yazım hatası veya eksik alanlar) düzeltmeniz gerekir. Bu, çıkışta doğru sonuç elde etme olasılığını artırır.
• Hedef bölgeniz, Coğrafi Kodlama API'sine kıyasla Address Validation API'den daha fazla meta veri (ör. bina türünün konut ve ticari olarak sınıflandırılması) döndürüyor.

Şu durumlarda Adres Doğrulama API'si üzerinden Coğrafi Kodlama'yı kullanmayı tercih edebilirsiniz:

• Birincil hedefiniz bir adresin konumunu almaktır ve adreslerin doğruluğu kritik olmayabilir.
  • Örneğin, büyük bir veri kümesinden ısı haritası oluşturmak için.
• Küresel bir çözüme ihtiyacınız var ve Adres Doğrulama API'si tüm hedef bölgelerde kullanılamıyor.

Aşağıda, Adres Doğrulama API'sinin, Coğrafi Kodlama API'sine kıyasla özelliklerini gösteren bazı örnekler verilmiştir.

Geçersiz Adres Örneği

1 Fake St, Mountain View, CA 94043, ABD

Address Validation API, bu girişi bağımsız adres bileşenlerine (sokak, şehir, eyalet vb.) ayırır. Ayrıca, adresin neden geçerli olmadığına dair ayrıntılı geri bildirim de verebilir (PREMISE düzeyine kadar).

Fake St, Mountain View, CA'da mevcut değildir ve Address Validation API, döndürülen bileşen düzeyindeki ayrıntılarda bunu yansıtır:

{
  "componentName": {
    "text": "Fake St",
    "languageCode": "en"
   },
   "componentType": "route",
   "confirmationLevel":"UNCONFIRMED_BUT_PLAUSIBLE"
 }

Bu durumda incelenmesi gereken önemli özellik confirmationLevel'tür. Sahte Sokak yerine UNCONFIRMED_BUT_PLAUSIBLE kodunu döndürerek API, bir sokağın adını kullanmanın mümkün olduğunu belirlemiştir ancak bu ad destek adres verileriyle eşleştirilemez.

API sonucunu geri bildirim olarak kullanarak, bu girişin sokak bileşeninde (Fake St) hata olduğu sonucuna varılabilir.

Coğrafi Kodlama API'si ile aynı adresi kullanarak, buradan deneyebilirsiniz. Coğrafi kodlama aracının ekran görüntüsünde gördüğünüz gibi "California" ile eşleşme sağlayabilir:

Ancak sonuç, girişteki hangi bileşenlerin hatalı olabileceğine dair minimum geri bildirim içeren, eyaletin tamamının coğrafi kodudur.

Yazım Hatası Örneği

76 Buckingamm Palace Road, Londn, SW1W 9TQ, GB

Yukarıdaki adreste, biri sokak adında, diğeri yerel bölgede olmak üzere birkaç yazım hatası var.

Hem Adres Doğrulama hem de Coğrafi Kodlama API'si bu hataları düzeltebilir ve 76 Buckingham Palace Road, Londra, SW1W 9TQ sonucuna ulaşabilir. Ancak Address Validation API, süreç hakkında daha fazla bilgi verebilir.

Girişte yanlış yazılan adres bileşenlerinden birine göz atın:

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

Address Validation API, alanda düzeltme yapıldığını belirten bir işaret döndürür. Düzeltmeyi veri sağlayıcıdan (ör. e-ticaret ödemesindeki bir müşteri) tekrar kontrol etmek için bu işaret doğrultusunda iş mantığı uygulanabilir.

Eksik Veri ve Yazım Hatası Örneği

Bollschestraße 86, 12587, DE

Yukarıdaki adresin sokak adında yazım hatası var ve Berlin'in şehri (mahalli) belirtilmemiş.

Address Validation API bu hataların her ikisini de düzeltebilir ve PREMISE düzeyinde bir coğrafi kod ve PREMISE düzeyinde doğrulanmış bir adres döndürür:

Bölschestraße 86, 12587 Berlin, DE

Coğrafi Kodlama API'si bu durumdaki giriş hatalarını başarıyla gideremez ve ZERO_RESULTS sonucunu döndürür.

Ek Adres Meta Veri Örneği

111 8th Avenue Ste 123, New York, NY 10011-5201, ABD

Binada bulunmayan birim numarası (Ste 123) dışında bu adres doğrudur.

Adres Doğrulama API'si, PREMISE (111 8. Cadde) adresini doğrulayabilir ve ticari bir mülk olması da dahil olmak üzere mülk hakkında bazı meta veriler sağlayabilir.

tesis:

"business": true

Ayrıca, yanıtta uspsData kapsamında döndürülen dpvConfirmation değeri S'dir:

"dpvConfirmation": "S"

dpvConfirmation değeri olan S, adresin PREMISE düzeyinde doğrulandığını ancak girişte sağlanan birim numarasının bu adresle ilişkili olmadığını gösterir.

Geocoding API, bu bilgiyi sağlayamaz.

Geocoding API yanıtını anlama

Genel Bakış

Geocoding API'yi kullanırsanız, coğrafi kodlama sonucu yanıtta, sağlanan adresin ayrıntılarını anlamak için kullanılabilecek çeşitli ipuçları içerir.

Geocoding API'nin çalışma şekli, adres bileşenlerini bir hiyerarşideki çözümlemektir.

Örneğin, 123 Example Street, Chicago, 60007, USA aşağıdaki sırayla çözülür:

/ Example Street/ Chicago/ 60007/ USA bu sırayla değerlendirilir. Bu örnekteki ilk eşleşme Chicago ve daha spesifik olarak 60007 Posta Kodu'dur. Söz konusu Posta Kodu için aşağıdaki Place_id değerini döndürür:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Geocode API, yanıtta aşağıdaki bilgileri içerir:

        "partial_match": true,
           "place_id": "ChIJwRKzf8ixD4gRHiXqucwr_HQ",
           "types": [
               "postal_code"
           ]

Geocoding API, bu adresin ne tür bir yere ait olduğunu onaylayabilir. Coğrafi Kodlama API'si tarafından döndürülen types adreslerinin listesini burada bulabilirsiniz.

Giriş bileşenlerinden hiçbiri çözülmezse API aşağıdakileri döndürür:

{
   "results": [],
   "status": "ZERO_RESULTS"
}

Bina numarası olmadan yalnızca sokak adresi içeren bir istek yaptığınızda aşağıdaki biçimde bir sonuç döndürülür:

"types": [
  "route"
]

Bu da Geocoding API'nin bir sokak numarasını bulamadığı veya eşleştiremediği anlamına gelir.

Not: Bir adres olup olmadığını öğrenmek için parametrelerden herhangi birinin (ör. types, partial_match, results, status)) Geocoding API yanıtında ayarlanıp ayarlanmadığını kontrol edin. Bu işlem, bir adresin mevcut olabileceğine dair güven düzeyini kademeli olarak artırır ancak adresin% 100 doğru olmasını sağlamaz. Bu nedenle Address Validation API'ye ihtiyacımız var.

Yalnızca Coğrafi Kodlama API yanıtından adres doğruluğuna olan güveni artırmak için yukarıdaki teknikleri kullanabilirsiniz. Ancak Address Validation API sonucundan farklı olarak Coğrafi Kodlama API'si, sonuç doğruluğunu belirlemek için tam geri bildirim döndürmez.

Yer türü

Bu bölümü doğru bir şekilde anlamak için bir Geocoding API yanıtından döndürülebilecek farklı konum türlerini anlamanız gerekir:

• ROOFTOP, döndürülen sonucun, açık adres kesinliğine kadar doğru konum bilgilerine sahip olduğumuz kesin bir coğrafi kod olduğunu belirtir.
• RANGE_INTERPOLATED, döndürülen sonucun iki kesin nokta (ör. kavşaklar) arasında interpole edilen bir yaklaşık değeri (genellikle bir yolda) yansıttığını gösterir. İnterpole edilmiş sonuçlar genellikle bir sokak adresi için çatı coğrafi kodları kullanılamadığında döndürülür.
• GEOMETRIC_CENTER, döndürülen sonucun bir poli çizgi (ör. sokak) veya poligon (bölge) gibi bir sonucun geometrik merkezi olduğunu gösterir.
• APPROXIMATE, döndürülen sonucun yukarıdakilerden hiçbiri olmadığını belirtir.

Bir Coğrafi Kodlama API'si ROOFTOP veya RANGE_INTERPOLATED değerinde bir location_type döndürürse bu, adresin var olduğu anlamına gelmez. Benzer şekilde, bir Coğrafi Kodlama API'si partial_match işareti true olarak ayarlanmış şekilde döndürülürse bu yine de sizin için doğru sonuç olabilir.

Bu tür yanlış eşleşmeler, Geocoding API ile çözülmesi çok zor bir sorundur. En azından, isteğin / yanıtın ülkesi ve yerelliği üzerinde bazı temel son işlem doğrulaması uygulayabilirsiniz. Daha da iyisi, gerçek sokak adreslerini yazım hataları ve/veya eksik adresler açısından karşılaştırın.

Not: Coğrafi Kodlama API'sini kullanmaya karar verirseniz ilk istek ile Coğrafi Kodlama API yanıtı arasında düzenli olarak veri kalitesi kontrolleri yapmanız önerilir.

Kısmi eşleme ve yanlış eşleme

Bir adres kısmi eşleşmeyse (yani Coğrafi Kodlama API'si adresi tam olarak tanımlayamadıysa) yanıtta şunlar yer alır:

"partial_match": true,
"types": [
           "locality",
           "political"
         ]

Yukarıdaki konum türlerinden daha da önemli olan, yanıtta partial_match = true olduğunda ne olacağını dikkate almaktır. partial_match Coğrafi Kodlama API'sinin, orijinal istek için tam eşleşme döndürmediğini, ancak istenen adresin bir kısmını eşleştirebildiğini gösterir.

Eksik adresle ilgili orijinal isteği incelemenizi öneririz. Kısmi eşleşmeler genellikle istekte belirtilen bölgede bulunmayan sokak adresleri için gerçekleşir. Bir istek aynı konumdaki iki veya daha fazla konumla eşleştiğinde kısmi eşleşmeler de döndürülebilir.

Örneğin, "21 Henr St, Bristol, UK" hem Henry Caddesi hem de Henrietta Caddesi için kısmi eşleşme döndürür. Bir istek yanlış yazılmış adres bileşeni içeriyorsa Coğrafi Kodlama API'sinin alternatif bir adres önerebileceğini unutmayın. Bu şekilde tetiklenen öneriler kısmi eşleşme olarak işaretlenmez.

Sentetik Adresler

Coğrafi Kodlama API'si, Google'ın veritabanında tam konum olarak bulunmayan "sentetik" adreslerin konumlarını döndürebilir.

Bu tür senaryolarda, yanıt nesnesi genellikle uzun bir Yer Kimliği ve şu özelliği içerir: geometry.location_type=APPROXIMATE.

Yanıtta bu göstergelerle karşılaşırsanız lütfen giriş adresini geçersiz olarak işaretleyin ve başka bir yöntemle yeniden doğrulamayı deneyin.

Not: Bu, Address Validation API'nin bir adres mevcut değilse doğrudan geri bildirim sağladığı başka bir örnektir.

Address Validation API yanıtını anlama

Address Validation API'den gelen yanıtları anlamaya yönelik harika dokümanlar hâlihazırda mevcut olduğundan, burada daha fazla ayrıntıya girmeyeceğiz.

• Yanıt nesnesine genel bakışı burada bulabilirsiniz.
• Yanıtın farklı bileşenlerini gösteren demoyu burada bulabilirsiniz
• Ödeme için adres doğrulama belgesinde, iyi ve kötü adresler arasındaki farkın nasıl anlaşılacağına dair ayrıntılı bir açıklama yer alır.

En iyi uygulamalar

Coğrafi bölgeyi belirtme

Adres Doğrulama veya Coğrafi Kodlama API'lerine çağrı yaparken, söz konusu adresin aranacağı coğrafi bölgeyi sınırlandırmayı denemek en iyi uygulamadır. İki API bunu iki farklı şekilde uygular:

• Geocoding API - Bölge Eğilimi

  Coğrafi kodların belirli bir ülkede olacağını biliyorsanız Bölge Eğilimi özelliğini kullanarak çok daha iyi sonuçlar elde edebilirsiniz. Örneğin, Kanada'da coğrafi kodlama yapıyorsanız Kanada'ya yönelik bir önyargı oluşturmak için isteklerinize &region=ca eklemenizi öneririz. Bölgesel önyargının yalnızca ilgili bölgedeki sonuçları tercih ettiğini unutmayın. Bölge dışındaki sonuçlara da erişebilirsiniz.

• Address Validation API - Region Code

  Benzer şekilde, Address Validation API'de regionCode alanı kullanılarak istek gönderilirken bir ISO2 kodu ile daha doğru sonuçlar elde edilir.

Yer kimliklerini depolama

Gelecekteki istekler için Google Haritalar Platformu'ndan konumla ilgili bilgileri depolamak istiyorsanız yer kimliğini konumun bir özelliği olarak veritabanınızda süresiz olarak depolayabilirsiniz. Her yer kimliği için yalnızca bir kez Yer Bulma isteği göndermeniz gerekir. Ayrıca, bir kullanıcı her işlem ayrıntısı istediğinde yer kimliğini arayabilirsiniz.

Her zaman en güncel bilgilere sahip olmak için place_id parametresini içeren bir Yer Ayrıntıları isteği kullanarak yer kimliklerini 12 ayda bir yenileyin.

Not: Coğrafi kodlamayla ilgili en iyi uygulamalar kılavuzunu da inceleyin.

Sonuç

Bu dokümanda, Adres Doğrulama ve Coğrafi Kodlama API'leri arasındaki temel farklar açıklanmaktadır. Özet olarak, aşağıdaki durumlarda Address Validation API'yi kullanmayı düşünün:

• Özellikle teslimatla ilgili amaçlar doğrultusunda doğru posta adresi gereklidir.
• Giriş verilerinin kalitesinin düşük olduğu biliniyor. Address Validation API, giriş hatalarına karşı daha toleranslıdır, doğrulanamayan adres bileşenlerini vurgular ve giriş verilerinde düzeltmeler yapar.
• Adres için daha fazla bilgi (ör. konut veya ticari) gerekir (belirli bölgelerde kullanılabilir).

Sonraki Adımlar

Güvenilir adreslerle ödeme, teslimat ve işlemleri iyileştirin teknik belgesini indirin ve Adres Doğrulama ile ödeme, teslimat ve işlemleri iyileştirme webinar'ını görüntüleyin.

Önerilen ek okuma:

• E-ticaret Ödemesi için Adres Doğrulama
• Yer Adı Otomatik Tamamlama Dokümanları
• Address Validation API Belgeleri
• Google Haritalar Platformu Raporlaması

Katkıda bulunanlar

Bu makale Google tarafından yönetilmektedir. Bu makaleyi ilk olarak aşağıdaki katkıda bulunanlar yazdı.

Ana yazarlar:

Henrik Valve | Çözüm Mühendisi

Thomas Anglaret | Çözüm Mühendisi

Sarthak Ganguly | Çözüm Mühendisi