Geocoding v3'ten v4'e geçiş

Avrupa Ekonomik Alanı (AEA) geliştiricileri

Fatura adresiniz Avrupa Ekonomik Alanı'ndaysa 8 Temmuz 2025'ten itibaren Hizmetler'i kullanımınızda Google Haritalar Platformu AEA Hizmet Şartları geçerli olacaktır. İşlevler bölgeye göre değişir. Daha fazla bilgi edinin.

Geocoding API v4, API'nin v3 sürümündeki işlevlerin yerini alan çeşitli yeni uç noktalar sunar. Bu kılavuzda, uygulamanızı yeni v4 uç noktalarını kullanacak şekilde nasıl taşıyacağınız gösterilmektedir.

Mevcut API anahtarlarınızı yeni v4 uç noktalarıyla kullanabilirsiniz. Ancak API'nin 3. sürümünde kota artışı talep ettiyseniz yeni 4. sürüm API'lerinde de artış talep etmeniz gerekir. JavaScript kullanıcıları için taşıma yolu yoktur.

Not: Önizleme sırasında Geocoding API v4 yöntemleri saniyede 25 sorgu (QPS) ile sınırlıdır. Daha yüksek kota isteğinde bulunma hakkında bilgi edinmek için Kotaları görüntüleme ve yönetme başlıklı makaleyi inceleyin ve hizmet olarak Geocoding API'yi seçin.

v3 İleri Coğrafi Kodlama'dan geçiş

Adresleri coğrafi olarak kodlamak için Coğrafi Kodlama'yı kullanıyorsanız GET isteğini kabul eden v4 Adres coğrafi kodlama uç noktasına geçiş yapmanız gerekir.

v4 API, çeşitli parametrelerin adlarını, yapısını ve desteğini değiştirir. Yanıtla döndürülmesini istediğiniz alanları belirtmek için alan maskesi kullanmanızı önemle tavsiye ederiz.

Uyarı: Tüm v4 uç noktalarında alan adları, v3 uç noktalarının kullandığı snake case'in (ör. address_components) aksine, küçük harfli camel case kullanılarak biçimlendirilir (ör. addressComponents). RPC yanıtları, v3'te olduğu gibi v4'te de snake case kullanmaya devam eder.

İstek parametresi değişiklikleri

v3 Parametresi	v4 Parametresi	Notlar
address, components	address	Yapılandırılmamış adres (v3 address) artık URL yolunda iletiliyor. Bileşen filtreleri (v3 components) artık address.* sorgu parametreleri olarak iletiliyor.
bounds	locationBias.rectangle	Yeniden adlandırıldı; yapı nesne olarak değiştirildi.
language	languageCode	Yeniden adlandırıldı.
region	regionCode	Yeniden adlandırıldı.
extra_computations	Kaldırıldı

Yanıt alanı değişiklikleri

v3 Alanı	v4 Alanı	Notlar
status, error_message	Kaldırıldı	v4, HTTP durum kodlarını ve hata gövdelerini kullanır.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Yeniden adlandırıldı.
results.geometry.location_type	results.granularity	Yeniden adlandırıldı.
results.geometry.location	results.location	Alan adları: lat/lng -> latitude/longitude.
results.geometry.viewport	results.viewport	Alan adları: northeast/southwest -> high/low.
results.postcode_localities	results.postalCodeLocalities	Yeniden adlandırıldı. Artık bir veya daha fazla yerleşim birimi için döndürülüyor (v3 > 1 olmalıdır).
results.partial_match	Kaldırıldı
Yeni	results.addressComponents.languageCode	Belirli adres bileşeninin dili.
Yeni	results.bounds	high/low kullanılarak açık sınırlar.
Yeni	results.place	Yerin kaynak adı.
Yeni	results.postalAddress	Yapılandırılmış PostalAddress nesnesi.

v3 Tersine Coğrafi Kodlama'dan taşıma

Koordinatları adreslere dönüştürmek için ters coğrafi kodlama kullanıyorsanız GET isteğini kabul eden v4 Ters coğrafi kodlama uç noktasına geçmeniz gerekir.

v4 API, çeşitli parametrelerin adlarını, yapısını ve desteğini değiştirir. Yanıtla döndürülmesini istediğiniz alanları belirtmek için alan maskesi kullanmanızı önemle tavsiye ederiz.

Uyarı: Tüm v4 uç noktalarında alan adları, v3 uç noktalarının kullandığı snake case'in (ör. address_components) aksine, küçük harfli camel case kullanılarak biçimlendirilir (ör. addressComponents). RPC yanıtları, v3'te olduğu gibi v4'te de snake case kullanmaya devam eder.

İstek parametresi değişiklikleri

v3 Parametresi	v4 Parametresi	Notlar
language	languageCode	Yeniden adlandırıldı.
region	regionCode	Yeniden adlandırıldı.
result_type	types	Yeniden adlandırıldı; tekrarlanan sorgu parametrelerini kullanıyor.
location_type	granularity	Yeniden adlandırıldı; tekrarlanan sorgu parametrelerini kullanıyor.
extra_computations	Kaldırıldı

Yanıt alanı değişiklikleri

v3 Alanı	v4 Alanı	Notlar
status, error_message	Kaldırıldı	v4, HTTP durum kodlarını ve hata gövdelerini kullanır.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Yeniden adlandırıldı.
results.geometry.location_type	results.granularity	Yeniden adlandırıldı.
results.geometry.location	results.location	Alan adları: lat/lng -> latitude/longitude.
results.geometry.viewport	results.viewport	Alan adları: northeast/southwest -> high/low.
Yeni	results.addressComponents.languageCode	Belirli adres bileşeninin dili.
Yeni	results.bounds	high/low kullanılarak açık sınırlar.
Yeni	results.place	Yerin kaynak adı.
Yeni	results.postalAddress	Yapılandırılmış PostalAddress nesnesi.

v3 Yer Coğrafi Kodlama'dan taşıma

Coğrafi Kodlama v3 ile belirli bir yer kimliğinin adresini almak için place_id kullanıyorsanız GET isteğini kabul eden v4 Yer Coğrafi Kodlama uç noktasına geçiş yapmanız gerekir.

v4 API, çeşitli parametrelerin adlarını, yapısını ve desteğini değiştirir. Yanıtla döndürülmesini istediğiniz alanları belirtmek için alan maskesi kullanmanızı önemle tavsiye ederiz.

Uyarı: Tüm v4 uç noktalarında alan adları, v3 uç noktalarının kullandığı snake case'in (ör. address_components) aksine, küçük harfli camel case kullanılarak biçimlendirilir (ör. addressComponents). RPC yanıtları, v3'te olduğu gibi v4'te de snake case kullanmaya devam eder.

İstek parametresi değişiklikleri

v3 Parametresi	v4 Parametresi	Notlar
place_id	place istek proto'sundaki alan	Yer kimliği artık yol parametresi places/{place} olarak sağlanıyor. Örneğin: https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Bu, temel isteğin yer alanıyla eşlenir.
language	languageCode	Yeniden adlandırıldı.
region	regionCode	Yeniden adlandırıldı.

Yanıt alanı değişiklikleri

v3 Alanı	v4 Alanı	Notlar
status, error_message	Kaldırıldı	v4, HTTP durum kodlarını ve hata gövdelerini kullanır.
results	(kök)	v4, results dizisi değil, tek bir sonuç nesnesi döndürür.
results.address_components.long_name/results.address_components.short_name	addressComponents.longText/addressComponents.shortText	Yeniden adlandırıldı.
results.geometry.location_type	granularity	Yeniden adlandırıldı.
results.geometry.location	location	Alan adları: lat/lng -> latitude/longitude.
results.geometry.viewport	viewport	Alan adları: northeast/southwest -> high/low.
results.postcode_localities	postalCodeLocalities	Yeniden adlandırıldı. Artık bir veya daha fazla yerleşim birimi için döndürülüyor (v3 > 1 olmalıdır).
Yeni	addressComponents.languageCode	Belirli adres bileşeninin dili.
Yeni	bounds	high/low kullanılarak açık sınırlar.
Yeni	place	Yerin kaynak adı.
Yeni	postalAddress	Yapılandırılmış PostalAddress nesnesi.

Geocoding Hyperlocal Data'dan hedeflere taşıma

Geocoding API v3'teki aşağıdaki özellikler, Geocoding API v4'ün SearchDestinations uç noktasıyla değiştiriliyor:

• Giriş sayısı
• Navigasyon noktaları
• Bina ana hatları
• Saha

Yukarıdaki özellikler için Geocoding API v3'ü kullanıyorsanız bu özellikleri almak için SearchDestinations uç noktasını kullanmanıza yardımcı olacak bu dokümanı inceleyin. Bu belgede, SearchDestinations API yanıtında bu özelliklerin nerede bulunacağı ve bu özelliklerin Geocoding API v3 ile Geocoding API v4'ün SearchDestinations uç noktasındaki API yanıtlarında nasıl temsil edildiği arasındaki farklar açıklanmaktadır.

Giriş sayısı

destination ile ilişkili girişleri almak için destination.entrances alanını kullanın.

entrance biçiminin, Geocoding API v3'teki giriş biçiminden biraz farklı olduğunu unutmayın. destination.entrances içindeki her girişte aşağıdaki alanlar bulunur:

• displayName: Bu, giriş için kullanıcılar tarafından okunabilen bir adın (ör. "B Kapısı") yer alacağı yeni bir isteğe bağlı alandır.
• location - Bu, Geocoding API v3'te kullanılan biçimden farklı olan LatLng türünde bir konumdur.
• tags - Bu, Geocoding API v3'teki girişlerin tags alanıyla aynıdır.
• place - Geocoding API v3'ten gelen girişlerin buildingPlaceId alanına benzer. Ancak bu alandaki yer kimliği, yalnızca bir bina için değil, herhangi bir türdeki bir yer için olabilir.

Navigasyon noktaları

Bir destination ile ilişkili gezinme noktalarını almak için destination.navigationPoints alanını kullanın.

navigationPoint biçiminin, Geocoding API v3'teki gezinme noktası biçiminden biraz farklı olduğunu unutmayın. destination.navigationPoints içindeki her gezinme noktasında aşağıdaki alanlar bulunur:

• displayName: Bu, gezinme noktasının kullanıcılar tarafından okunabilen bir adının olacağı yeni bir isteğe bağlı alandır (ör. "5. Cadde").
• location - Bu, Geocoding API v3'te kullanılan biçimden farklı olan LatLng türünde bir konumdur.
• travelModes - Bu, Geocoding API v3'teki gezinme noktalarının restrictedTravelModes alanına benzer. Olası enum değerleri aynıdır. Tek fark, bu alanın artık kısıtlanmış ulaşım şekillerini değil, navigasyon noktası için kabul edilebilir ulaşım şekillerini temsil etmesidir.
• usage: Bu, gezinme noktası tarafından desteklenen kullanım alanlarını içeren yeni bir alandır. Çoğu gezinme noktasında UNKNOWN kullanımı olduğunu ancak bunun, gezinme noktasının kullanımının herhangi bir şekilde kısıtlandığı anlamına gelmediğini unutmayın.

Bina ana hatları

Bir destination ile ilişkili bina ana hatlarını almak için destination içindeki binaları temsil eden placeView nesnelerinin displayPolygon alanını kullanmanız gerekir. Her placeView için placeView.structureType alanını kullanarak bunun bir bina olup olmadığını kontrol edebilirsiniz. Yapı türü BUILDING ise taslağı placeView.displayPolygon alanından alabilirsiniz. placeView, Geocoding API v3'te bulunmayan bina için ek alanlar da içerir.

Not: Belirli bir konumdaki bina poligonunu mu arıyorsunuz? Sonuçları daraltmak için isteğinizde placeFilter parametresini kullanabilirsiniz. Yalnızca bina sonuçlarını döndürmek için structureType değerini placeFilter içinde "BUILDING" olarak ayarlayın. Poligon elde etmek önceliğinizse (kesin adreslerin olmadığı konumlar için bile) mevcut en hassas poligonu döndürmek üzere placeFilter içinde addressability değerini "ANY" olarak ayarlayın.

Örnek

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

Bir destination, aşağıdaki alanlarda bir binayı temsil eden bir placeView nesnesi içerebilir:

• destination.primary - Bu, hedef için birincil yerdir.
• destination.containingPlaces: Bu, birincil yeri "içeren" daha büyük yerleri barındırabilen yinelenen bir alandır. Örneğin, birincil yer bir subpremise ise containingPlaces genellikle binayı temsil eden placeView öğesini içerir.
• destination.subDestinations: Bu, birincil yerin alt hedeflerini barındırabilen yinelenen bir alandır. Örneğin, bir binanın bağımsız daire birimleri. Bu alanda genellikle binayı temsil eden bir placeView bulunmaz.

placeView.displayPolygon biçiminin, RFC 7946 biçimi kullanılarak GeoJSON biçimi olan Geocoding API v3'teki bina ana hattı biçimiyle eşleştiğini unutmayın.

Saha

Binaların ana hatlarını oluşturmaya benzer şekilde, bir destination ile ilişkili arazileri almak için destination içindeki arazileri temsil eden placeView nesnelerinin displayPolygon alanını kullanmanız gerekir. Her placeView için placeView.structureType alanı ile gerekçe olup olmadığını kontrol edebilirsiniz. Yapı türü GROUNDS ise ana hattı placeView.displayPolygon alanından alabilirsiniz. placeView, Geocoding API v3'te bulunmayan gerekçeler için ek alanlar da içerir.

Bir destination, aşağıdaki alanlarda bir gerekçeyi temsil eden bir placeView nesnesi içerebilir:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

placeView.displayPolygon biçiminin, Geocoding API v3'teki yer şekilleri ana hatları biçimiyle (RFC 7946 biçimini kullanan GeoJSON biçimi) eşleştiğini unutmayın.

Bu özellikleri istemek için alan maskesi kullanın

SearchDestinations uç noktasının, Döndürülecek alanları seçme bölümünde açıklandığı gibi bir alan maskesi gerektirdiği unutulmamalıdır. Tüm alanları döndürmek için alan maskesi * olarak ayarlanabilir veya almak istediğiniz belirli alanlara ayarlayabilirsiniz. Örneğin, aşağıdaki API isteği, bir hedefin girişlerini, gezinme noktalarını, bina ana hatlarını ve arazilerini almak için gereken tüm alanları alacak şekilde alan maskesini ayarlar:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations