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, Google Haritalar Platformu'nun müşterilerin bir adresin doğru olup olmadığını doğrulamalarına yardımcı olan bir teklifidir.

Geocoding API ile coğrafi kodlama, adresleri coğrafi koordinatlara dönüştürme işlemidir. Bu koordinatları, haritaya işaretçi yerleştirmek veya harita üzerinde bir konuma işaret koymak 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 edin ve 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ı, 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 adreslerinizde 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 üzerinden ç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 bazı durumlarda, hedeflerinizi karşılamak için her iki ürünü de kullanmanız gerekebilir.

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

• Şüpheli verilerin yüksek olduğu veya yanlış adres alınmasının olumsuz bir etkisi olacağı yerler. Bunun nedeni, Address Validation API'nin bir girişin neden yüksek hassasiyetli bir sonuç almadığıyla ilgili 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 Adres Doğrulama API'sinden daha fazla meta veri döndürür (ör. bina türü, konut veya ticari olarak sınıflandırılır).

Aşağıdaki durumlarda Address Validation API yerine Geocoding'i 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

Adres Doğrulama API'si bu girişi ayrı adres bileşenlerine (cadde, ş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. API, Fake St için UNCONFIRMED_BUT_PLAUSIBLE döndürerek bir caddenin adının bu olabileceğini belirlemiştir ancak bu ad, destekleyici 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 de yerleşim yerinde 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, London, 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üzeltmenin veri sağlayıcıyla (ör. e-ticaret ödemesindeki bir müşteri) tekrar kontrol edilmesi için bu işarete karşı iş mantığı uygulanabilir.

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

Bollschestraße 86, 12587, DE

Yukarıdaki adreste sokak adında yazım hatası var ve Berlin şehri (yerleşim yeri) eksik.

Address Validation API, bu hataların ikisini de düzeltebilir ve PREMISE düzeyinde bir coğrafi kod ile 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 Verileri Örneği

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

Bu adres, binada bulunmayan daire numarası (Ste 123) dışında 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ğerinin S olması, adresin PREMISE düzeyinde doğrulandığını ancak girişte sağlanan daire numarasının bu adresle ilişkili olmadığını gösterir.

Geocoding API bu bilgileri sağlayamaz.

Geocoding API yanıtını anlama

Genel Bakış

Coğrafi Kodlama API'yi kullanıyorsanı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, adres bileşenlerini hiyerarşik olarak çözerek çalışır.

Ö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 durumda ilk eşleşme Chicago ve daha spesifik olarak 60007 posta kodudur. Bu nedenle, söz konusu posta kodu için aşağıdaki Place_id döndürülür:

ChIJwRKzf8ixD4gRHiXqucwr_HQ

Coğrafi kodlama API'si 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 durum, Geocoding API'nin bir sokak numarası bulamadığı veya eşleştiremediği anlamına gelir.

Not: Bir adresin mevcut olup olmadığını öğrenmek için Coğrafi Kodlama API yanıtında parametrelerden herhangi birinin (ör. types, partial_match, results, status)) ayarlanıp ayarlanmadığını kontrol edin. Bu işlem, bir adresin var olabileceğine dair güven düzeyini kademeli olarak artırsa da% 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 Adres Doğrulama API'sinin aksine, Coğrafi Kodlama API'si, sonucun doğruluğunu belirlemek için tam geri bildirim döndürmez.

Yer türü

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

• ROOFTOP, döndürülen sonucun, sokak adresi hassasiyetine kadar doğru konum bilgilerine sahip olduğumuz hassas bir coğrafi kod olduğunu gösterir.
• 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. Düzenlenmiş sonuçlar genellikle bir sokak adresi için çatı jeokodları 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ıdakilerin hiçbiri olmadığını gösterir.

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ülse bile 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 için bazı temel son işlem doğrulama işlemleri 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şleşme ve yanlış eşleşme

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 ne zaman kullanıldığını dikkate almaktır. partial_match, Coğrafi Kodlama API'sinin istenen adresin bir kısmını eşleştirebilmesine rağmen orijinal istek için tam eşleşme döndürmediğ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ı bölgedeki iki veya daha fazla konumla eşleştiğinde de kısmi eşleşmeler 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ış bir 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 aşağıdaki ö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ın nasıl anlaşılacağıyla ilgili mükemmel dokümanlar zaten mevcut olduğundan burada ayrıntılı bilgi vermeyeceğ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ı gönderirken, 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 Yanlışlığı ö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, regionCode alanı kullanılarak istekte bir ISO2 kodu iletilirse daha doğru sonuçlar verir.

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, şu durumlarda Address Validation API'yi kullanabilirsiniz:

• Özellikle teslim edilebilirlik amacıyla doğru bir 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ştirme teknik belgesini indirin ve Adres Doğrulama ile ödeme, teslimat ve işlemleri iyileştirme webinar'ını görüntüleyin.

Önerilen diğer kaynaklar:

• 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 yazmıştır.

Başlıca yazarlar:

Henrik Valve | Çözüm Mühendisi

Thomas Anglaret | Çözüm Mühendisi

Sarthak Ganguly | Çözüm Mühendisi