Geocoding API hızlı referansı

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

Geocoding API: Sık yapılan yanlışlar

  • Sorun: Alan maskesi olmayan SearchDestinations istekleri hata vererek başarısız oluyor. GeocodeAddress, GeocodeLocation ve GeocodePlace'nın aksine alan maskesi zorunludur. Düzeltme: Her SearchDestinations isteğinde X-Goog-FieldMask üstbilgisini veya $fields parametresini ayarlayın. /maps/documentation/geocoding/choose-fields adresini inceleyin.
  • Sorun: v4'te GeocodeAddress katı bileşen filtresi (v3 components=country:US) yoktur. Yapılandırılmış address.* parametreleri tek bir adreste birleştirilir ve sonuçları filtrelemez; regionCode parametresinin de v4'te varsayılan değeri yoktur (v3'te varsayılan değer us idi). Çözüm: results parametresini istemci tarafında filtreleyin: Büyük harfli regionCode parametresini postalAddress.regionCode ile eşleştirin; büyük harfli 2 harfli idari alanları postalAddress.administrativeArea ve administrative_area_level_n addressComponents (shortText) ile eşleştirin; hem girişi hem de postalAddress.postalCode parametresini 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ğunda placeFilter.addressability değerini PRIMARY olarak 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_components değil, addressComponents) kullanır, status ve error_message alanlarını kaldırır ve results dizisi yerine GeocodePlace alanı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 v4 SearchDestinations yö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.