Geocoding API, adresleri koordinatlara ve yer kimliklerine, koordinatları veya yer kimliklerini ise adreslere dönüştüren bir web hizmetidir. v4 SearchDestinations yöntemi; bina girişleri, navigasyon noktaları, bina ve arazi ana hatları ve yakındaki önemli noktalar gibi varış noktası ayrıntılarını da döndürür.
Geocoding API: Temel bilgiler
- Ürün: Geocoding API
- Kategori: Yerler
- Platform: Web hizmeti (REST)
- Çalıştığı yer: Sunucu (arka uç kodu)
- Lansman aşaması: GA
- Yaşam döngüsü: Etkin
- Genel bakış: Geocoding API'ye genel bakış
Geocoding API: Ne zaman kullanılır?
Geocoding API'yi şu durumlarda kullanın:
- Arka uç sunucunuzda bir açık adresi enlem/boylam koordinatlarına ve yer kimliğine dönüştürmeniz gerekir.
- GPS koordinatları veya bilinen bir Yer Kimliği için görünen adres ya da bağlı olduğu yer (şehir, posta kodu) gerekir.
- Sürücüleri veya kuryeleri bir hedefe yönlendirmek için bina girişlerine, rota oluşturulabilir navigasyon noktalarına ya da bina/arazi ana hatlarına ihtiyacınız vardır.
- Büyük bir kompleksin (havaalanı, alışveriş merkezi, kampüs) içindeki bir hedefi alt hedeflere veya yakındaki önemli noktalara ayırmanız gerekir.
Geocoding API'yi şu durumlarda kullanmayın:
- İstemci tarafı tarayıcı JavaScript'inden coğrafi kodlamaya ihtiyacınız var. Açık bir API anahtarıyla v4'ü çağırmak güvenlik riski oluşturur. Bunun yerine Maps JavaScript API'yi kullanın.
- Coğrafi kodlanmış hedefe giden rotayı veya TVS'yi hesaplamanız gerekir. Bunun yerine Routes API'yi kullanın.
- Android uygulamasında bir navigasyon noktası jetonuna adım adım rehberlik almanız gerekiyorsa Android için Navigasyon SDK'sı'nı kullanın.
- iOS uygulamasında bir navigasyon noktası jetonuna adım adım rehberlik almanız gerekiyor. Bunun yerine iOS için Navigasyon SDK'sı'nı kullanın.
Geocoding API: kurulum
- Etkinleştirilecek hizmet:
geocoding-backend.googleapis.com - Kimlik doğrulama: API anahtarı, OAuth 2.0, hizmet hesabı
- Başlayın: Geocoding API'yi ayarlama
- Referans: Geocoding API referansı
- Fiyatlandırma: Geocoding API kullanımı ve faturalandırması
- Politikalar: Geocoding API politikaları
- Sürüm notları: Geocoding API sürüm notları
Geocoding API: İlgili ürünler
- Genellikle birlikte kullanıldığı ürünler: Routes API, Android için Navigation SDK, iOS için Navigation SDK
Geocoding API: Sık yapılan yanlışlar
- Sorun: Alan maskesi olmayan
SearchDestinationsistekleri hata vererek başarısız oluyor.GeocodeAddress,GeocodeLocationveGeocodePlace'nın aksine alan maskesi zorunludur. Düzeltme: HerSearchDestinationsisteğindeX-Goog-FieldMasküstbilgisini veya$fieldsparametresini ayarlayın. /maps/documentation/geocoding/choose-fields adresini inceleyin. - Sorun: v4'te
GeocodeAddresskatı bileşen filtresi (v3components=country:US) yoktur. Yapılandırılmışaddress.*parametreleri tek bir adreste birleştirilir ve sonuçları filtrelemez;regionCodeparametresinin de v4'te varsayılan değeri yoktur (v3'te varsayılan değerusidi). Çözüm:resultsparametresini istemci tarafında filtreleyin: Büyük harfliregionCodeparametresinipostalAddress.regionCodeile eşleştirin; büyük harfli 2 harfli idari alanlarıpostalAddress.administrativeAreaveadministrative_area_level_naddressComponents(shortText) ile eşleştirin; hem girişi hem depostalAddress.postalCodeparametresini normalleştirin (boşlukları/tireleri kaldırın ve bölge kurallarını uygulayın). /maps/documentation/geocoding/geocoding-v4-migrate adresini inceleyin. - Sorun: Geocoding API v4'ü doğrudan tarayıcı JavaScript'inden çağırmak API anahtarını açığa çıkarır. HTTP yönlendiren kısıtlamaları,
Refererüstbilgisi taklit edilerek atlatılabilir. Düzeltme: Kendi arka ucunuzdan korumalı bir anahtarla v4'ü çağırın veya istemci tarafı ihtiyaçları için Maps JavaScript API Coğrafi Kodlama Hizmeti'ni (v3 arka ucu) kullanın. /maps/documentation/geocoding/geocoding-v4-migrate adresini inceleyin. - Sorun:
SearchDestinations, v3 ve diğer v4 yöntemlerinin aksine, kesin bir birincil adresi olmayan sonuçlar döndürebilir. Düzeltme: Yalnızca tam birincil adresleri içeren sonuçlara ihtiyacınız olduğundaplaceFilter.addressabilitydeğeriniPRIMARYolarak ayarlayın. /maps/documentation/geocoding/geocoding-v4-migrate adresini inceleyin. - Sorun: Geocoding API v3 için yazılan kod, v4 REST yanıtlarında çalışmaz: v4, lowerCamelCase alan adlarını (
address_componentsdeğil,addressComponents) kullanır,statusveerror_messagealanlarını kaldırır veresultsdizisi yerineGeocodePlacealanından tek bir kök nesne döndürür. Düzeltme: v4 REST çağrılarında HTTP durum kodlarını ve hata gövdelerini kontrol edin, lowerCamelCase alanlarını (addressComponents,postalAddress) okuyun ve gRPC yanıtlarının hâlâ snake_case kullandığını unutmayın. /maps/documentation/geocoding/geocoding-v4-migrate adresini inceleyin.
Geocoding API: Eski ve desteği sonlandırılmış özellikler
- Geocoding API v3 yakın çevreye özel verileri (
extra_computations:BUILDING_AND_ENTRANCES,NAVIGATION_POINTS,GROUNDS; yanıt alanlarıbuildings.entrances,navigation_points,buildings.building_outlines,grounds): 13.08.2025'ten itibaren desteği sonlandırıldı. Değişiklik: Geocoding API v4SearchDestinationsyöntemi (POST /v4/geocode/destinations). Geçiş rehberini inceleyin.
Geocoding API ile yapabilecekleriniz
Her görev için aşağıda bağlantısı verilen kılavuzlara bakın veya Özellikler Gezgini'nde ürünleri karşılaştırın.
- Bir adresin enlem/boylam koordinatlarını döndürme (coğrafi kodlama)
- Bir dizi enlem/boylam koordinatının adresini döndürme (tersine coğrafi kodlama)
- Coğrafi kodlama isteğini, belirli bir görüntü alanındaki sonuçları döndürecek şekilde kısıtlayın. Not: Geocoding API v4'te locationBias, sonuçları kesin olarak kısıtlamak yerine belirtilen görüntü alanına göre yönlendirir.
- Coğrafi kodlama veya tersine coğrafi kodlama isteğini yalnızca belirli bir bölge, ülke veya posta kodu içindeki sonuçları döndürecek şekilde kısıtlayın. Not: Geocoding API v4'te regionCode, sonuçları kesin olarak kısıtlamak yerine belirli bir CLDR bölgesine göre önceliklendirir. Ülkeye veya posta koduna göre eski v3 bileşen filtreleme için https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering adresini ziyaret edin.
- Tersine coğrafi kodlama isteğini yalnızca belirtilen adres türleri için sonuç döndürecek şekilde kısıtlayın. Not: Geocoding API v4'te types parametresi, temel aramayı kısıtlamak yerine aramadan sonra döndürülen tersine coğrafi kodlama sonuçlarını adres türüne göre filtreler.
- Bir adresin önemli noktalara veya bölgelere yakınlığı hakkında bilgi döndürür.
- Bir dizi enlem/boylam koordinatı için önemli noktalara veya alanlara yakınlık hakkında bilgi döndürür.
- Bir Google yer tanımlayıcısı için önemli noktalara veya alanlara yakınlık hakkında bilgi döndürür.
- Google yer tanımlayıcısı için adresi döndürme
- Bir adres için bina ana hattının enlem/boylam koordinatlarını döndürme
- Bir dizi enlem/boylam koordinatı için bina ana hattının enlem/boylam koordinatlarını döndürür.
- Google yer tanımlayıcısı için bir bina ana hattının enlem/boylam koordinatlarını döndürme
- Bir adres için bina girişinin enlem/boylam koordinatlarını döndürür.
- Bir enlem/boylam koordinat kümesi için bina girişinin enlem/boylam koordinatlarını döndürür.
- Google Place tanımlayıcısı için bir bina girişinin enlem/boylam koordinatlarını döndürme