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

Hedef

Genellikle bir yerin konumunu doğrulamak için ihtiyaç duyarsınız. Google Haritalar Platformu'nda bu kullanım alanında size yardımcı olabilecek birkaç farklı hizmet vardır. Bu belge, iki birincil konum doğrulama hizmeti olan Address Validation API ve Geocoding API arasında seçim yapmanıza yardımcı olur.

Adres Doğrulama API'si, müşterilerin bir adresin doğru olup olmadığını doğrulamasına yardımcı olan bir Google Haritalar Platformu teklifidir.

Coğrafi Kodlama API'si ile coğrafi kodlama, adreslerin coğrafi koordinatlara dönüştürülmesi işlemidir. Bu koordinatları, bir haritaya veya harita üzerindeki bir konuma işaretçi yerleştirmek için kullanabilirsiniz.

Adres Doğrulama ile Coğrafi Kodlama API'si arasındaki farklılıklara dair genel bakışı burada bulabilirsiniz.

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

Adres Doğrulama ve Coğrafi Kodlama API'si ne zaman tercih edilmelidir?

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

• Kullanıcı etkileşimi kullanım alanı, kullanıcının sonuçlarla etkileşimde bulunmak için mevcut olduğu durumları ifade eder.
• Yerler Otomatik Tamamlama bir JavaScript API'si olduğundan Kullanıcı Arayüzleriyle entegrasyon için uygundur.
• Mevcut adreslerinizdeki veri kalitesi sorunlarından haberdar olabilirsiniz. Bu nedenle, sadece coğrafi kodlar kullanmak istiyor olsanız da veri kümelerini düzeltmek için bu konumları Address Validation API ile çalıştırmanız önerilir.

Yukarıdaki karar ağacına bağlı olarak, ürünlerden birini diğerine tercih etmeye karar verebileceğiniz birçok durum vardır. Ancak diğer durumlar, hedeflerinizi karşılamak için her iki ürünü de kullanmayı içerebilir.

Şu durumlarda Coğrafi Kodlama API'si yerine Address Validation API'yi kullanmayı tercih edebilirsiniz:

• Veriler büyük olasılıkla şüpheli veriler veya yanlış bir adres almanın satış sürecini olumsuz şekilde nasıl etkileyeceğini gösterir. Bunun nedeni Address Validation API'nin bir girişin neden yüksek kesinliğe sahip sonuç almadığı hakkında daha fazla geri bildirim sağlamasıdır.
• Kullanıcı girişlerini (ör.yazım hataları veya eksik alanlar) düzeltmeniz gerekir. Bu da çıktıda doğru sonuç alma 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 döndürür (ör. bina türünün konut ve ticari olarak sınıflandırılması).

Şu durumlarda Address Validation API yerine Coğrafi Kodlama'yı kullanmayı tercih edebilirsiniz:

• Birincil hedefiniz bir adresin konumunu almaktır ve tek tek adreslerin doğruluğu kritik olmayabilir.
  • Örneğin, büyük bir veri kümesinden ısı haritası oluşturabilirsiniz.
• Genel bir çözüm kullanmanız gerekir. Adres Doğrulama API'si tüm hedef bölgelerde kullanılamaz.

Aşağıda, Adres Doğrulama API'si özelliklerinin Coğrafi Kodlama API'siyle karşılaştırmasını 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 PREMISE düzeyine kadar geçerli olmadığına dair ayrıntılı geri bildirim de sağlayabilir.

Sahte St, Mountain View, CA'da mevcut değildir. Adres Doğrulama API'si, döndürülen bileşen düzeyi ayrıntılarında bu durumu yansıtır:

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

Bu durumda denetlenmesi gereken önemli özellik confirmationLevel değeridir. API, Sahte St yerine UNCONFIRMED_BUT_PLAUSIBLE değerini döndürerek bir sokağın bu ada sahip olabileceğini belirlemiştir. Ancak söz konusu ad, destekleyici adres verileriyle eşleştirilemez.

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

Coğrafi Kodlama API'si ile aynı adresi kullanarak, buradan deneyebileceğiniz coğrafi kodlama aracından alınan ekran görüntüsünde gördüğünüz gibi, "Kaliforniya"da eşleşme sağlanabilir:

Bununla birlikte, sonuçta, girişteki hangi bileşenlerin potansiyel olarak hatalı olduğuna ilişkin çok az geri bildirim içeren, tüm eyaletin bir coğrafi kodu elde edilir.

Yazım Hatası Örneği

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

Yukarıdaki adres, biri sokak adında, diğeri ise şehirde olmak üzere birkaç yazım hatası içeriyor.

Hem Address Validation hem de Geocoding API, bu hataları düzelterek 76 Buckingham Palace Road, Londra, SW1W 9TQ sonucunu elde edebilmektedir. 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 bir düzeltme yapıldığını belirten bir işaret döndürür. Veri sağlayıcısıyla (örneğin, e-ticaret ödeme işlemindeki bir müşteri) düzeltmeyi tekrar kontrol etmek için bu işarete iş mantığı uygulanabilir.

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

Bollschestraße 86, 12587, Almanya

Yukarıdaki adreste sokak adında bir yazım hatası var ve Berlin'in şehri (mahali) eksik.

Address Validation API her iki hatayı da 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 gelinemez 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 birim numarası (Ste 123) dışında doğrudur.

Address Validation API, PREMISE adresindeki adresi (111 8. Cadde) doğrulayabilir ve tesisin ticari olup olmadığı gibi meta verileri sağlayabilir.

yer tutucular:

"business": true

Buna ek olarak, yanıttaki uspsData öğesinin bir parçası olarak döndürülen dpvConfirmation değeri S olur:

"dpvConfirmation": "S"

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

Coğrafi Kodlama API'si bu bilgiyi sağlayamaz.

Coğrafi Kodlama API'sı yanıtını anlama

Genel bakış

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

Coğrafi Kodlama API'sinin çalışma şekli, adres bileşenlerini bir hiyerarşide çözümlemektir.

**Örnekte 123 Example Street, Chicago, 60007, USA aşağıdaki sırayla çözümlenir:

/ Example Street/ Chicago/ 60007/ USA bu sırayla değerlendirilir. Bu durumda ilk eşleşme İstanbul ve daha spesifik olarak 60007 Posta Kodu olur. Bu nedenle, söz konusu Posta Kodu için şu 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"
           ]

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

Girişin bileşenlerinden hiçbiri çözümlenmemişse API şunu döndürür:

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

Bina numarası olmayan sadece açık adresle istekte bulunursanız şu formda bir sonuç döndürülür:

"types": [
  "route"
]

Bu da Coğrafi Kodlama API'sinin bir sokak numarasını bulamadığı veya eşleştiremediği anlamına gelir.

Not: Bir adresin mevcut 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'si yanıtından elde edilen adres doğruluğuyla ilgili güveni artırmak için yukarıdaki teknikleri kullanabilirsiniz. Ancak Adres Doğrulama API'si sonucundan farklı olarak Coğrafi Kodlama API'si, sonuçların 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 Coğrafi Kodlama API'si yanıtından döndürilebilecek 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 (kavşaklar gibi) arasında interpolasyon yapılan bir yaklaşık (genellikle bir yolda) yansıttığını belirtir. İnterpolasyon 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 çoklu çizgi (örneğin, sokak) veya poligon (bölge) gibi bir sonucun geometrik merkezi olduğunu belirtir.
• APPROXIMATE, döndürülen sonucun yukarıdakilerden hiçbiri olmadığını belirtir.

Coğrafi Kodlama API'sinin location_type değeri ROOFTOP veya RANGE_INTERPOLATED döndürürse bu, adresin mevcut 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 sizin için doğru sonuç olabilir.

Bu tür yanlış eşleştirme, Coğrafi Kodlama API'si ile çözülmesi çok zor bir sorundur. En azından isteğin / yanıtın ülkesi ve bulunduğu ülke ve bölgeye yönelik bazı temel işlem sonrası doğrulamalarını uygulamayı düşünebilirsiniz. Daha da iyisi, yazım hataları ve/veya eksik adres olup olmadığını görmek için gerçek açık adresleri karşılaştırmaya çalışın.

Not: Geocoding API'yi kullanmaya karar verirseniz ilk istek ve Geocoding API yanıtı arasında düzenli olarak veri kalitesi kontrolleri yapmanız önerilir.

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

Bir adres kısmi bir eşleşmeyse (Coğrafi Kodlama API'sinin adresi tam olarak tanımlayamadığı anlamına gelirse) yanıt şunları içerir:

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

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

Eksik adres olup olmadığını görmek için orijinal isteği incelemek isteyebilirsiniz. Kısmi eşleşmeler çoğunlukla istekte belirtilen şehir içinde bulunmayan açık adresler için meydana gelir. Bir istek aynı konumdaki 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", Henry Street ve Henrietta Street 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'si alternatif bir adres önerebilir. Bu şekilde tetiklenen öneriler, kısmi eşleşme olarak işaretlenmez.

Sentetik Adresler

Coğrafi Kodlama API'si, Google'ın veritabanında kesin konumlar olarak bulunmayan "yapay" adresler için konumlar döndürebilir.

Bu tür senaryolarda, yanıt nesnesi genellikle uzun bir Place ID 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şaretleyip başka bir yolla yeniden doğrulamayı deneyin.

Not: Bu, Address Validation API'de bir adres olmadığında 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ın nasıl anlaşılacağıyla ilgili harika dokümanlar 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 belgesi için Adres Doğrulama belgesinde, iyi ve kötü adreslerin nasıl ayırt edileceğine ilişkin ayrıntılı bir açıklama bulunmaktadır.

En iyi uygulamalar

Coğrafi konumu belirtme

Adres Doğrulama veya Coğrafi Kodlama API'lerinden birine çağrı yaparken en iyi uygulama, söz konusu adresin aranacağı coğrafi konumu sınırlamaya çalışmaktır. İki API bunu iki farklı şekilde uygular:

• Geocoding API - Bölgeye Ağırlık Verme

  Coğrafi kodların belirli bir ülke içinde olacağını biliyorsanız Bölgeye Ağırlık Verme kullanarak çok daha iyi sonuçlar elde edersiniz. Örneğin, Kanada'da coğrafi kodlama yapıyorsanız Kanada'ya yönelik ağırlık verme isteklerinize &region=ca eklemenizi öneririz. Bölgeye Ağırlık Vermenin yalnızca o bölgedeki sonuçları tercih ettiğini lütfen unutmayın. Bölge dışında sonuçları yine de alabilirsiniz.

• Address Validation API - Bölge Kodu

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

Yer kimliklerini depolama

Gelecekteki isteklerde kullanmak üzere Google Haritalar Platformu'ndan konumla ilgili bilgileri depolamak için yer kimliğini, veritabanınızda konumun bir özelliği olarak süresiz olarak depolayabilirsiniz. Her yer kimliği için yalnızca bir kez Yer Bulma isteğinde bulunmanız gerekir. Kullanıcılar 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 bir Yer Ayrıntıları isteği kullanarak 12 ayda bir yer kimliklerini yenileyin.

Not: Coğrafi Kodlama ile ilgili en iyi uygulamalar kılavuzunu da incelemeyi unutmayın.

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 teslimatla ilgili amaçlar için doğru bir posta adresi gereklidir.
• Giriş verilerinin düşük kalitede olduğu biliniyor. Address Validation API, giriş hatalarını daha hoş görür, doğrulanamayan adres bileşenlerini vurgular ve giriş verilerinde düzeltmeler yapar.
• Konut veya İş Yeri gibi bir adres için daha fazla bilgi 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 web seminerini görüntüleyin.

Önerilen daha fazla bilgi:

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

Katılımcılar

Bu makale Google tarafından saklanmaktadır. Mesajı ilk olarak aşağıdaki katkıda bulunanlar yazmış.

Baş yazarlar:

Henrik Valve | Çözüm Mühendisi

Thomas Anglaret | Çözüm Mühendisi

Sarthak Ganguly | Çözüm Mühendisi