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 belge, iki temel konum doğrulama hizmeti olan 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ğrulaması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 haritada bir konum belirlemek için kullanabilirsiniz.

Address Validation API ile Geocoding API arasındaki farkların üst düzey bir özetini burada bulabilirsiniz.

Hemen deneyin: Google Cloud Console'u ziyaret edin ve Address Validation API ile Places API'yi etkinleştirin.

Address Validation API ve Geocoding API'yi ne zaman kullanmalısınız?

Yukarıdaki akış grafiğiyle ilgili notlar:

• Kullanıcı etkileşimi kullanım alanı, kullanıcının sonuçlarla etkileşim kurmak için hazır bulunduğu zamanı 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 istiyor olsanız bile 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 diğer durumlarda hedeflerinize ulaşmak için her iki ürünü de kullanmanız gerekebilir.

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

• Sorgulanabilir verilerin yüksek olasılıkla bulunduğu veya yanlış adres almanın sonraki aşamalarda olumsuz etki yaratacağı durumlarda. Bunun nedeni, Address Validation API'nin bir girişin neden yüksek hassasiyetli sonuç almadığı hakkında daha fazla geri bildirim sağlamasıdır.
• Kullanıcı girişlerini (ör.yazım hatası veya eksik alanlar) düzeltmeniz gerekir. Bu da çıkışta doğru sonuç elde etme olasılığını artırır.
• Hedef bölgeniz, Adres Doğrulama API'sinden Coğrafi Kodlama API'sine kıyasla daha fazla meta veri (ör. bina türünün konut veya ticari olarak sınıflandırılması) döndürür.

Aşağıdaki durumlarda Adres Doğrulama API'si yerine Geocoding API'yi kullanmayı tercih edebilirsiniz:

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

Aşağıda, Geocoding API ile karşılaştırıldığında Address Validation API'nin ö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 PREMISE düzeyinde ayrıntılı geri bildirim de verebilir.

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

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

Bu durumda incelenmesi gereken önemli özellik confirmationLevel'dır. API, Fake St için UNCONFIRMED_BUT_PLAUSIBLE döndürerek bir sokağın bu adı almasının mümkün olacağını belirlemiş ancak destekleyici adres verileriyle eşleştirilemediğini tespit etmiştir.

API sonucunu geri bildirim olarak kullanarak bu girişin sokak bileşeninin (Fake St) hatalı olduğu anlaşılabilir.

Aynı adresi Coğrafi Kodlama API'si ile kullanarak, buradan deneyebileceğiniz coğrafi kodlama aracının ekran görüntüsünde gördüğünüz gibi "California" ile eşleşme yapabilir:

Ancak sonuç, girişin hangi bileşenlerinin hatalı olabileceğiyle ilgili minimum geri bildirimle birlikte eyaletin tamamının coğrafi kodu olur.

Yazım Hatası Örneği

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

Yukarıdaki adreste biri sokak adında, diğeri ise yerleşim yerinde olmak üzere iki 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 sonucunu elde edebilir. Ancak, Adres Doğrulama API'si bu işlem hakkında daha fazla bilgi verebilir.

Giriş sırasında 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. E-ticaret ödeme sürecindeki bir müşteri gibi veri sağlayıcıyla düzeltmeyi iki kez kontrol etmek için bu işaretle ilgili işletme 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.

Adres Doğrulama API'si 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 durumda giriş hatalarının üstesinden başarıyla gelemez ve ZERO_RESULTS sonucunu döndürür.

Ek Adres Meta Verisi Örneği

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

Bu adres, bina içinde bulunmayan birim numarası (Ste 123) hariç olmak üzere doğrudur.

Adres Doğrulama API'si, adresi PREMISE (111 8th Ave) olarak doğrulayabilir ve mülk hakkında bazı meta veriler (ör. ticari bir mülk olduğu) sağlayabilir.

tesisler:

"business": true

Ayrıca, yanıttaki uspsData bölümünde döndürülen dpvConfirmation değeri S'dir:

"dpvConfirmation": "S"

dpvConfirmation değeri S ise adresin PREMISE düzeyinde doğrulandığını ancak girişte belirtilen birim numarasının bu adresle ilişkilendirilmediğini gösterir.

Geocoding API bu bilgiyi sağlayamaz.

Geocoding API yanıtını anlama

Genel Bakış

Geocoding 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ümlenir:

/ Example Street/ Chicago/ 60007/ USA sırasıyla değerlendirilir. Bu durumda ilk eşleşme Chicago ve daha spesifik olarak 60007 posta kodu. Bu nedenle, 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 doğrulayabilir. Coğrafi kodlama API'si tarafından döndürülen adres types listesini burada bulabilirsiniz.

Girişin hiçbir bileşeni çözümlenmezse API şu yanıtı döndürür:

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

Sadece sokak adresiyle ve bina numarası olmadan yapılan istekler şu biçimde bir sonuç döndürür:

"types": [
  "route"
]

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

Not: Bir adresin var olup olmadığını öğrenmek için Geocoding 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ırır ancak% 100 doğru sonuç vermez. Bu nedenle Adres Doğrulama API'sine ihtiyacımız var.

Yalnızca bir Coğrafi Kodlama API yanıtından elde edilen adres doğruluğuna olan güveni artırmak için yukarıdaki teknikleri kullanabilirsiniz. Ancak Adres Doğrulama API'si sonucunun aksine, Geocoding API, sonuç 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, konum bilgilerinin sokak adresi kesinliğine kadar doğru olduğu kesin bir coğrafi kod olduğunu gösterir.
• RANGE_INTERPOLATED, döndürülen sonucun iki kesin nokta (ör. kavşaklar) arasında enterpolasyonla hesaplanmış bir yaklaşıma (genellikle bir yol üzerinde) karşılık geldiğini gösterir. Bir sokak adresi için çatı coğrafi kodları kullanılamadığında genellikle enterpolasyonlu sonuçlar döndürülür.
• GEOMETRIC_CENTER, döndürülen sonucun bir çoklu ç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ı gösterir.

Geocoding API, location_type ROOFTOP veya RANGE_INTERPOLATED 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 olan bir sorundur. En azından, istek / yanıtın ülke ve yerel ayarı üzerinde bazı temel işlem sonrası doğrulama işlemlerini uygulayabilirsiniz. Daha da iyisi, yazım hataları ve/veya eksik adres olup olmadığını görmek için gerçek sokak adreslerini karşılaştırın.

Not: Geocoding API'yi kullanmaya karar verirseniz ilk istek ile Geocoding 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şme ise (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 önemlisi, yanıtta partial_match = true olduğunda bunu dikkate almaktır. partial_match, Geocoding API'nin 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 incelemek isteyebilirsiniz. Kısmi eşleşmeler en sık, istekte belirtilen yerleşim biriminde bulunmayan sokak adresleri için gerçekleşir. Bir istek aynı yerleşim yerindeki 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 istekte yanlış yazılmış bir adres bileşeni varsa Coğrafi Kodlama API'sinin alternatif bir adres önerebileceğini unutmayın. Bu şekilde tetiklenen öneriler kısmi eşleşme olarak işaretlenmez.

Yapay Adresler

Geocoding API, Google'ın veritabanında tam konum olarak bulunmayan"sentezlenmiş" adreslerin konumlarını döndürebilir.

Bu gibi senaryolarda yanıt nesnesi genellikle uzun bir yer kimliği ve şu özelliği içerir: geometry.location_type=APPROXIMATE.

Yanıtla ilgili 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, Adres Doğrulama API'si ile bir adresin mevcut olmaması durumunda doğrudan geri bildirim aldığınız başka bir örnektir.

Address Validation API yanıtını anlama

Address Validation API'den gelen yanıtları anlama konusunda zaten harika bir doküman 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ı nasıl anlayacağınız ayrıntılı olarak açıklanmaktadır.

En iyi uygulamalar

Coğrafi konum belirtme

Address Validation veya Geocoding API'lerine çağrı yaparken söz konusu adresi arayacağınız coğrafi bölgeyi sınırlamaya çalışmak en iyi uygulamadır. İki API, bunu iki farklı şekilde uygular:

• Geocoding API - Bölgeye Göre Önyargı

  Coğrafi kodların belirli bir ülke içinde olacağını biliyorsanız bölgeye göre önyargı kullanarak çok daha iyi sonuçlar elde edebilirsiniz. Örneğin, Kanada'da coğrafi kodlama yapıyorsanız Kanada'ya yönelik önyargı oluşturmak için isteklerinize &region=ca eklemenizi öneririz. Bölgesel önyargının yalnızca o bölgedeki sonuçları tercih ettiğini unutmayın. Bölgenin dışındaki sonuçları almaya devam edebilirsiniz.

• Address Validation API - Bölge Kodu

  Benzer şekilde, Adres Doğrulama API'si, regionCode alanı kullanılarak istekte bir ISO2 kodu iletilirse daha doğru sonuçlar üretir.

Yer kimliklerini depolama

Google Haritalar Platformu'ndan alınan konum bilgilerini gelecekteki istekler için depolamak istiyorsanız yer kimliğini veritabanınızda konumun bir özelliği olarak süresiz şekilde depolayabilirsiniz. Her yer kimliği için yalnızca bir kez Yer Bulma isteğinde bulunmanız gerekir. Ayrıca, bir kullanıcı işlem ayrıntılarını her istediğinde yer kimliğini arayabilirsiniz.

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

Not: Lütfen Coğrafi Kodlama ile ilgili en iyi uygulamalar kılavuzunu da inceleyin.

Sonuç

Bu belgede, Adres Doğrulama ve Coğrafi Kodlama API'leri arasındaki temel farklar açıklanmaktadır. Özetle, şu durumlarda Adres Doğrulama API'sini kullanabilirsiniz:

• Özellikle teslim edilebilirlik açısından doğru bir posta adresi gereklidir.
• Giriş verilerinin kalitesinin düşük olduğu bilinmektedir. 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 gerekir. Örneğin, Konut ve Ticari (belirli bölgelerde kullanılabilir).

Sonraki Adımlar

Güvenilir adreslerle ödeme, teslimat ve operasyon süreçlerini iyileştirme başlıklı teknik incelemeyi indirin ve Adres Doğrulama ile ödeme, teslimat ve operasyon süreçlerini iyileştirme başlıklı web seminerini izleyin.

Daha fazla bilgi için önerilen kaynaklar:

• E-ticaret ödemesi için Address Validation
• Otomatik Yer Tamamlama Dokümanları
• Address Validation API Belgeleri
• Google Haritalar Platformu Raporlaması

Katkıda bulunanlar

Bu makale Google tarafından sağlanmaktadır. Bu makale ilk olarak aşağıdaki katkıda bulunanlar tarafından yazılmıştır.

Başlıca yazarlar:

Henrik Valve | Çözüm Mühendisi

Thomas Anglaret | Çözüm Mühendisi

Sarthak Ganguly | Çözüm Mühendisi