Hedef
Bir yerin konumunu doğrulamanız gereken durumlar olabilir. Google Haritalar Platformu'nda bu kullanım alanında size yardımcı olabilecek birkaç farklı hizmet vardır. Bu doküman, 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, müşterilerin bir adresin doğru olup olmadığını doğrulamasına yardımcı olan bir Google Haritalar Platformu teklifidir.
Geocoding API ile coğrafi kodlama, adresleri coğrafi koordinatlara dönüştürme işlemidir. Bu koordinatları, haritaya işaretçi veya konum yerleştirmek için kullanabilirsiniz.
Address Validation ve Geocoding API arasındaki farklara genel bakışı burada bulabilirsiniz.
Address Validation ve Geocoding API arasında seçim yapma
Yukarıdaki akış şemasıyla ilgili notlar:
- Kullanıcı etkileşimi kullanım alanı, bir kullanıcının sonuçlarla etkileşim kurmak için hazır bulunduğu durumları ifade eder.
- Places Autocomplete, bir JavaScript API'si olduğundan kullanıcı arayüzleriyle entegrasyon için uygundur.
- Mevcut adreslerinizde veri kalitesi sorunları olabilir. Bu nedenle, yalnızca coğrafi kodları isteseniz 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 bazı 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:
- Verilerin şüpheli olma ihtimali yüksekse veya yanlış adres almanın olumsuz bir etkisi olacaksa Bunun nedeni, Address Validation API'nin bir girişin neden yüksek hassasiyetli bir 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, çıktıda doğru sonuç alma olasılığını artırır.
- Hedef bölgeniz, Geocoding API'ye kıyasla Address Validation API'den 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 Address Validation API yerine Geocoding API'yi kullanmayı tercih edebilirsiniz:
- Birincil hedefiniz bir adresin konumunu almaksa ve her bir adresin doğruluğu kritik önem taşımıyorsa
- Örneğin, büyük bir veri kümesinden ısı haritası oluşturmak isteyebilirsiniz.
- Bina girişleri, bina ana hatları veya teslim alma ve bırakma navigasyon noktaları gibi hiper yerel varış noktası ayrıntılarına ihtiyacınız varsa (Geocoding API v4'teki SearchDestinations yöntemiyle kullanılabilir).
- Global bir çözüme ihtiyacınız varsa ve Address Validation API tüm hedef bölgelerde kullanılamıyorsa
Aşağıda, Address Validation API'nin Geocoding API'ye 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 ayrı adres bileşenlerine (sokak, şehir, eyalet vb.) ayırır. Ayrıca, adresin neden geçerli olmadığına dair PREMISE düzeyine kadar ayrıntılı geri bildirim de sağlayabilir.
Mountain View, CA'da Fake St adında bir sokak yoktur. 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 özelliğidir. API, Fake St için UNCONFIRMED_BUT_PLAUSIBLE döndürerek bir sokağın bu adı almasının mümkün olduğunu ancak destekleyici adres verileriyle eşleştirilemediğini belirlemiştir.
API sonucu geri bildirim olarak kullanıldığında bu girişin sokak bileşeninin (Fake St) hatalı olduğu anlaşılabilir.
Geocoding API ile aynı adres kullanıldığında, Geocoder aracından alınan aşağıdaki ekran görüntüsünde gösterildiği gibi "California" ile eşleşme yapılabilir:
Ancak sonuç, eyaletin tamamının coğrafi kodudur ve girişteki hangi bileşenlerin hatalı olabileceğine dair minimum geri bildirim içerir.
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 birkaç yazım hatası var.
Hem Address Validation hem de Geocoding API bu hataları düzeltebilir ve 76 Buckingham Palace Road, Londra, SW1W 9TQ sonucunu elde edebilir. Ancak Address Validation API, süreç 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 bir düzeltme yapıldığını belirten bir işaret döndürür. İşletme mantığı, veri sağlayıcıyla düzeltmeyi tekrar kontrol etmek için bu işarete göre uygulanabilir (ör. e-ticaret ödeme sayfasındaki bir müşteri).
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 her 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
Geocoding API, bu durumda giriş hatalarını başarıyla gideremez 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, binada bulunmayan daire numarası (Ste 123) dışında doğrudur.
Address Validation API, adresi PREMISE (111 8th Ave) olarak doğrulayabilir ve mülkle ilgili bazı meta veriler (ör. ticari bir mülk olduğu) sağlayabilir.
premises:
"business": true
Ayrıca, yanıttaki uspsData kapsamında döndürülen dpvConfirmation değeri S şeklindedir:
"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 bilgiyi sağlayamaz.
Geocoding API yanıtını anlama
Genel Bakış
Geocoding API'yi kullanıyorsanı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.
Geocoding API, adres bileşenlerini bir hiyerarşi içinde çözümler.
Örneğin, 123 Example Street, Chicago, 60007, USA şu sırayla çözümlenir:
/ Example Street/ Chicago/ 60007/ USA bu sırayla değerlendirilir. Bu örnekteki 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 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. Geocoding API tarafından döndürülen adres types listesini burada bulabilirsiniz.
Girişin bileşenlerinden hiçbiri çözümlenmezse API şunu döndürür:
{
"results": [],
"status": "ZERO_RESULTS"
}
Bina numarası olmadan yalnızca açık adresle yapılan bir istek, şu biçimde bir sonuç döndürür:
"types": [
"route"
]
Bu, 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 Geocoding API yanıtında parametrelerden herhangi birinin (ör. types, partial_match, results, status)) ayarlanıp ayarlanmadığını kontrol edin. Bu, bir adresin mevcut olabileceğine dair güven düzeyini kademeli olarak artırır ancak %100 doğru olmasını sağlamaz. Address Validation API'ye bu nedenle ihtiyacımız var.
Yalnızca Geocoding API yanıtından adres doğruluğuna olan güveni artırmak için yukarıdaki teknikleri kullanabilirsiniz. Ancak Address Validation API sonucunun aksine Geocoding API, sonuç doğruluğunu belirlemek için kesin geri bildirim döndürmez.
Yer türü
Bu bölümü doğru şekilde anlamak için 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 düzeyine kadar doğru konum bilgisine sahip olduğumuz 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 hesaplanan bir yaklaşık değeri (genellikle bir yol üzerinde) yansıttığını gösterir. Ara değer hesaplamalı sonuçlar genellikle bir açık adres için çatı coğrafi kodları kullanılamadığında döndürülür.
- GEOMETRIC_CENTER, döndürülen sonucun çoklu çizgi (ör. sokak) veya çokgen (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'nin ROOFTOP veya RANGE_INTERPOLATED değerinde bir location_type döndürmesi, adresin mevcut olduğu anlamına gelmez. Benzer şekilde, Geocoding API partial_match işaretini true olarak ayarlayarak döndürürse bu 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, istek/yanıtın ülke ve bölgesi üzerinde bazı temel işlem sonrası doğrulama adımları uygulayabilirsiniz. Daha da iyisi, yazım hataları ve/veya eksik adresler için gerçek açık adresleri 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şmeyse (yani Geocoding API 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 değerinin olup olmadığını dikkate almaktır. partial_match, Geocoding API'nin orijinal istekle tam eşleşme döndürmediğini ancak istenen adresin bir kısmını eşleştirebildiğini gösterir.
Orijinal isteği inceleyerek adresin eksik olup olmadığını kontrol edebilirsiniz. Kısmi eşleşmeler genellikle istekte belirtilen bölgede bulunmayan açık adresler 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 Street hem de Henrietta Street için kısmi eşleşme döndürür. Bir istekte yanlış yazılmış bir adres bileşeni varsa Geocoding API'nin 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"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 ile bir adres mevcut değilse 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ı nasıl anlayacağınızla ilgili mükemmel dokümanlar zaten mevcut. Bu nedenle 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 Address Validation belgesinde, iyi ve kötü adreslerin nasıl ayırt edileceğine dair ayrıntılı bir açıklama yer alır.
En iyi uygulamalar
Coğrafi bölgeyi belirtme
Address Validation veya Geocoding API'lerine çağrı yaparken, söz konusu adresin aranacağı 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 Öncelik Verme
Coğrafi kodların belirli bir ülkede olacağını biliyorsanız Bölge Eğilimi'ni kullanarak çok daha iyi sonuçlar elde edersiniz. Örneğin, Kanada'da coğrafi kodlama yapıyorsanız Kanada'ya öncelik vermek için isteklerinize
®ion=caeklemenizi öneririz. Bölgeye göre yönlendirmenin yalnızca ilgili bölgedeki sonuçları tercih ettiğini unutmayın. Bölge dışından sonuçlar almaya devam edebilirsiniz.Address Validation API - Bölge Kodu
Benzer şekilde, istekte
regionCodealanı kullanılarak bir ISO2 kodu iletilirse Address Validation API daha doğru sonuçlar üretir.
Yer kimliklerini depolama
Gelecekteki istekler için Google Haritalar Platformu'ndan konumla ilgili bilgileri depolamak istiyorsanız yer kimliğini veritabanınızda konumun bir özelliği olarak süresiz olarak depolayabilirsiniz. Her placeID için yalnızca bir kez Find Place isteğinde bulunmanız gerekir. Bir kullanıcı işlem ayrıntılarını her istediğinde yer kimliğini de 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 her 12 ayda bir yenileyin.
Not: Lütfen Geocoding ile ilgili en iyi uygulamalar kılavuzunu da inceleyin.
Sonuç
Bu belgede, Address Validation API ile Geocoding API arasındaki temel farklar açıklanmaktadır. Özetle, Address Validation API'yi aşağıdaki durumlarda kullanabilirsiniz:
- Özellikle teslimat amacıyla doğru bir posta adresi gereklidir.
- Giriş verilerinin kalitesinin düşük olduğu biliniyor. Address Validation API, giriş hatalarına karşı daha esnektir, doğrulanamayan adres bileşenlerini vurgular ve giriş verilerinde düzeltmeler yapar.
- Adres için daha fazla bilgi (ör. konut veya ticari) gerekiyor (belirli bölgelerde kullanılabilir).
Sonraki Adımlar
Güvenilir adreslerle ödeme, teslimat ve operasyonları iyileştirme başlıklı teknik incelemeyi indirin ve Address Validation ile ödeme, teslimat ve operasyonları iyileştirme konulu web seminerini izleyin.
Önerilen ek kaynaklar:
- E-ticaret ödeme sayfasında Address Validation
- Yer Adı Otomatik Tamamlama Belgeleri
- Address Validation API belgeleri
- Google Haritalar Platformu raporları
Katkıda bulunanlar
Bu makale Google tarafından hazırlanmıştır. Bu makale, aşağıdaki katkıda bulunanlar tarafından yazılmıştır.
Asıl yazarlar:
Henrik Valve | Çözüm Mühendisi
Thomas Anglaret | Çözüm Mühendisi
Sarthak Ganguly | Çözüm Mühendisi