Geocoding v3'ten v4'e geçiş

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

Mevcut API anahtarlarınızı yeni v4 yöntemleriyle kullanabilirsiniz. Ancak API'nin 3. sürümünde kota artışı istediyseniz yeni 4. sürüm API'lerinde artış isteğinde bulunmanız gerekir.

v3 İleri Coğrafi Kodlama'dan taşıma

Adresleri coğrafi olarak kodlamak için v3 Geocoding'i kullanıyorsanız GET isteğini kabul eden v4 Geocode an address yöntemine 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.

İstek parametresi değişiklikleri

Yanıt alanı değişiklikleri

v3 bileşen filtrelerini yeniden üretme

Geocoding v3'teki İleri Coğrafi Kodlama, belirli bileşenler için sonuçların sıkı bir şekilde filtrelenmesini sağlayan bir components parametresi içeriyordu (ör. components=country:US). v4'teki İleri Coğrafi Kodlama, istek parametrelerinde bu tür bir sıkı filtrelemeyi desteklemez. v4'te adres bilgilerini yoldaki tek bir yapılandırılmamış dize olarak veya address.addressLines, address.locality, address.administrativeArea, address.postalCode ve address.regionCode gibi yapılandırılmış sorgu parametreleri olarak sağlayabilirsiniz. Yapılandırılmış parametreler kesin filtre olarak işlev görmez. Bunun yerine, sağlanan tüm bileşenler birleştirilerek API'nin coğrafi kodlamaya çalışacağı tam adres oluşturulur. API, tüm bileşenlerde belirtilen adresin tamamı için en iyi eşleşmeyi arar. Bileşenleri yapılandırılmış bir şekilde sağlamak, özellikle adres bilgileri ayrı form alanlarından toplandığında API'nin amacı daha iyi anlamasına yardımcı olabilir. Her alandaki bilgi türü net olduğundan bu, API'nin her bileşendeki küçük yazım hatalarını veya belirsizlikleri işlemesine yardımcı olabilir.

v3'ün katı bileşen filtrelerine benzer bir davranış elde etmek için v4 API'si tarafından döndürülen results dizisinde, yanıttaki postalAddress ve addressComponents nesnelerine göre istemci tarafı filtreleme uygulamanız gerekir.

Aşağıdaki tabloda, v3 components filtreleri ile v4 postalAddress alanları arasındaki en iyi eşleşme gösterilmektedir:

İstemci tarafı filtreleme örnekleri

Aşağıdaki örneklerde, desteklenen alanlar (ülke, idari bölge ve posta kodu) için sonuçların v3 bileşen filtrelemeye benzer şekilde nasıl filtreleneceği gösterilmektedir. Güvenilir filtreleme ölçütleri olmadığından diğer alanlara göre filtreleme yapmanız önerilmez.

Ülkeye göre filtreleme

Talebinizdeki address.regionCode ile her sonuçtaki postalAddress.regionCode öğesini eşleştirin. API, istekte küçük harfli bölge kodlarını kabul etse de yanıtta her zaman büyük harfli olarak döndürür. Bu nedenle, karşılaştırma yapmadan önce girişinizi büyük harfe dönüştürmeniz gerekir.

def filter_by_country(results, region_code):
    return [
        res for res in results
        if res.get('postalAddress', {}).get('regionCode') == region_code.upper()
    ]

# Example usage:
# v4_response = ... # API call response
# filtered = filter_by_country(v4_response.get('results', []), 'US')

function filterByCountry(results, regionCode) {
    return results.filter(res => res.postalAddress?.regionCode === regionCode.toUpperCase());
}

// Example usage:
// const v4Response = ... # API call response
// const filtered = filterByCountry(v4Response.results, 'US');

İdari bölgeye göre filtrele

Talebinizdeki address.administrativeArea ile her sonuçtaki postalAddress.administrativeArea öğesini eşleştirin. Ülke kodlarına benzer şekilde, karşılaştırma yapmadan önce girişinizi büyük harfe dönüştürerek normalleştirmeniz gerekir. Bu yalnızca isteğinizdeki administrativeArea standart 2 harfli kısaltmayla sağlandığında güvenilirdir. Yanıtın postalAddress.administrativeArea değeri, çeşitli nedenlerle ISO 3166-2 kodu sonekleriyle doğrudan eşleşmeyebilir. Öncelikle, bazı bölgelerde ISO 3166-2 koduna karşılık gelen alt bölüm, posta adreslerinin standart gösteriminin bir parçası değildir. Örneğin, İspanya'da addressComponents içinde 1.düzey idari bölge (ör. Kanarya Adaları için "CN") bulunabilir ancak postalAddress.administrativeArea içinde 2.düzey bölge (ör. "Santa Cruz de Tenerife") yer alabilir. İkinci olarak, bazı bölgelerde alt bölümün kısaltması yaygın olarak kullanılmaz ve postalAddress.administrativeArea ile daha uzun bir adla gösterilir (benzer nedenlerle, alt bölüme karşılık gelen adres bileşeni için addressComponents.shortText, alt bölümün ISO 3166-2 kodu sonekiyle eşleşmeyebilir). Ayrıca, bazı durumlarda alt bölüm, n'nin 1'den büyük olduğu administrative_area_level_n için adres bileşeninde gösterilebilir. En kapsamlı sonuçlar için hem postalAddress.administrativeArea hem de administrative_area_level_n türünde (ör. administrative_area_level_1) bir addressComponents ile eşleşme olup olmadığını kontrol etmeniz gerekir.

def filter_by_admin_area(results, admin_area):
    target = admin_area.upper()
    filtered = []
    for res in results:
        # Check postalAddress
        pa_aa = res.get('postalAddress', {}).get('administrativeArea', '')
        if pa_aa == target:
            filtered.append(res)
            continue
        # Check all administrative area levels in addressComponents
        for comp in res.get('addressComponents', []):
            is_admin_level = any(t.startswith('administrative_area_level_')
                               for t in comp.get('types', []))
            if is_admin_level:
                short = comp.get('shortText', '')
                if short == target:
                    filtered.append(res)
                    break
    return filtered

# Example usage:
# filtered = filter_by_admin_area(v4_response.get('results', []), 'CA')

function filterByAdminArea(results, adminArea) {
    const target = adminArea.toUpperCase();
    return results.filter(res => {
        // Check postalAddress.administrativeArea
        if (res.postalAddress?.administrativeArea === target) {
            return true;
        }
        // Check addressComponents for any administrative area level
        return res.addressComponents?.some(c => {
            const isAdmin = c.types?.some(t => t.startsWith('administrative_area_level_'));
            return isAdmin && c.shortText === target;
        });
    });
}

// Example usage:
// const filtered = filterByAdminArea(v4Response.results, 'CA');

Posta koduna göre filtreleme

Talebinizdeki address.postalCode ile her sonuçtaki postalAddress.postalCode öğesini eşleştirin. Karşılaştırma yapmadan önce hem giriş hem de sonuç posta kodlarını normalleştirmeniz gerekir. Normalleştirme mantığı, bölgeye büyük ölçüde bağlıdır. Temel yaklaşımda boşluklar ve tireler kaldırılır ve tutarlı bir büyük/küçük harf biçimine dönüştürülür.

Posta kodu ön eklerini (ör. Birleşik Krallık'taki "L2") veya soneklerini (ör. ABD posta kodlarındaki "+4") işlemek için daha gelişmiş normalleştirme gerekebilir. Gerekli normalleştirme mantığı, ülkeye ve ilgili posta kodlarının biçimlerine göre değişir. Sağlanan normalleştirme işlevlerini uyarlamanız veya hedeflediğiniz bölgeler için daha karmaşık bir mantık uygulamanız gerekebilir.

Sağlanan örnek, ABD posta kodlarını işler ve ZIP+4 kodu sağlansa veya döndürülse bile 5 haneli tabanla eşleşmeye izin verir.

import re

def normalize_postal_code_us(pc):
    # Basic normalization for US: uppercase, alphanumeric only
    if not pc:
        return ""
    normalized = re.sub(r'[^A-Z0-9]', '', pc.upper())
    # Return only the first 5 digits for US ZIP codes
    return normalized[:5]

def filter_by_postal_code_us(results, postal_code):
    normalized_input = normalize_postal_code_us(postal_code)
    if not normalized_input:
        return []
    filtered_results = []
    for res in results:
        pa_pc = res.get('postalAddress', {}).get('postalCode', '')
        if normalize_postal_code_us(pa_pc) == normalized_input:
            filtered_results.append(res)
    return filtered_results

# Example usage:
# Matches '94043', '94043-1351', '940431351'
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043')
# filtered = filter_by_postal_code_us(v4_response.get('results', []), '94043-1234')

function normalizePostalCodeUs(pc) {
    // Basic normalization for US: uppercase, alphanumeric only
    const normalized = (pc || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
    // Return only the first 5 digits for US ZIP codes
    return normalized.substring(0, 5);
}

function filterByPostalCodeUs(results, postalCode) {
    const normalizedInput = normalizePostalCodeUs(postalCode);
    if (!normalizedInput) {
        return [];
    }
    return results.filter(res => {
        const paPc = res.postalAddress?.postalCode || '';
        return normalizePostalCodeUs(paPc) === normalizedInput;
    });
}

// Example usage:
// Matches '94043', '94043-1351', '940431351'
// const filtered = filterByPostalCodeUs(v4Response.results, '94043');
// const filtered = filterByPostalCodeUs(v4Response.results, '94043-1234');

v3 Tersine Coğrafi Kodlama'dan geçiş

Koordinatları adreslere dönüştürmek için v3 Ters Coğrafi Kodlama'yı kullanıyorsanız GET isteğini kabul eden v4 Bir konumun ters coğrafi kodunu alma yöntemine 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.

İstek parametresi değişiklikleri

Yanıt alanı değişiklikleri

v3 adres tanımlayıcılarından taşıma

Coğrafi Kodlama v3 ile bir konum hakkında ek bilgi almak için address_descriptor kullanıyorsanız SearchDestinationsResponse öğesinin landmarks alanını kullanmaya geçmeniz gerekir.

v3 Place Geocoding'den 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 Place Geocoding yöntemine 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.

İstek parametresi değişiklikleri

Yanıt alanı değişiklikleri

Coğrafi kodlama hiper yerel verilerini hedeflere taşıma

Geocoding API v3'teki aşağıdaki özelliklerin yerini Geocoding API v4'ün SearchDestinations yöntemi alıyor:

• 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 yöntemini kullanmanıza yardımcı olacak bu dokümandan yararlanın. Bu belgede, SearchDestinations yanıtında bu özelliklerin nerede bulunacağı ve Geocoding API v3 ile Geocoding API v4'ün SearchDestinations yönteminde bu özelliklerin API yanıtlarında nasıl gösterildiğ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, LatLng türünde bir konumdur ve Geocoding API v3'te kullanılan biçimden farklıdır.
• 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, LatLng türünde bir konumdur ve Geocoding API v3'te kullanılan biçimden farklıdır.
• 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 ana hattı placeView.displayPolygon alanından alabilirsiniz. placeView, Geocoding API v3'te bulunmayan bina için ek alanlar da içerecektir.

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'yi tutar.
• 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çimini kullanan Geocoding API v3'teki bina ana hattı biçimi ile eşleştiğini unutmayın. Bu biçim, GeoJSON biçimidir.

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çerecektir.

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

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

placeView.displayPolygon biçiminin, RFC 7946 biçimini kullanan GeoJSON biçimi olan Geocoding API v3'teki yerleşim yeri ana hatları biçimiyle eşleştiğini unutmayın.

Sonuçların kesinliği

Geocoding API v3'te, yanıttaki geometri bölümünde yer alan location_type alanı, sonuçların hassasiyetini belirtiyordu ve bazı istemciler sonuçları bu değerlere (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER ve APPROXIMATE) göre sıralıyor veya filtreliyordu. Standart Geocoding API v4 geçişlerinde bu alan granularity olarak yeniden adlandırıldı.

Destinations API'de (v4 SearchDestinations) location_type alanı yoktur. Bunun yerine, mekansal bilgiler farklı şekilde işlenir:

• Manuel olarak istemci tarafı filtreleme yapılması gerekmez: Standart coğrafi kodlama, farklı ayrıntı düzeylerinde birden fazla sonuç sağlarken SearchDestinations yöntemi, mümkün olduğunda tek bir optimize edilmiş hedefi çözerek belirsizliği en aza indirir. Bu sayede müşterilerin, hangi sonucun en iyi olduğunu belirlemek için konum türüne göre filtreleme yapmasına gerek kalmaz.
• Yapı türü ve görüntüleme poligonlarıyla temsil edilen uzamsal bilgiler: Uzamsal geometri ve yapı şu şekilde belirtilir:
  • displayPolygon (tam geometri için).
  • placeView nesnesindeki structureType alanı.
• Yapı türü eşleme:
  • structureType, POINT, BUILDING veya SECTION ROOFTOP, genellikle daha önce ROOFTOP olarak adlandırılanla eşleşir.
  • structureType GROUNDS genellikle GEOMETRIC_CENTER ile eşleşir.

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

SearchDestinations yöntemi, Döndürülecek alanları seçme bölümünde açıklandığı gibi bir alan maskesi gerektirir. 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/v4/geocode/destinations

Güvenlikle ilgili olarak göz önünde bulundurulması gerekenler

Geocoding API v4, sunucudan sunucuya API olarak tasarlanmıştır. JavaScript kullanıcıları için v3'ten v4'e doğrudan geçiş yolu yoktur. API anahtarı kullanarak v4 yöntemlerini doğrudan istemci tarafı JavaScript'ten (örneğin, tarayıcıda) çağırmak, API anahtarınızın çalınma ve kötüye kullanılma riskini artırır.

HTTP yönlendiren kısıtlamaları faydalı olsa da web hizmeti uç noktaları için yeterli koruma sağlamaz. Çünkü bu kısıtlamalar, isteklerinde Referer başlığını sahteleştiren saldırganlar tarafından kolayca atlatılabilir.

Önerilen yaklaşım

Geocoding API v4'ü kullanmak için kendi arka uç sunucunuzu kullanmanız önerilir. İstemci uygulamanız bu aracı sunucuya istekte bulunmalıdır. Bu sunucu daha sonra, korumalı bir API anahtarı (ör. ortam değişkeninde veya gizli yöneticiye depolanan bir anahtar) kullanarak Google API'sini güvenli bir şekilde çağırır. Bu sayede, API anahtarınızın hiçbir zaman ön uç kodunda gösterilmemesi sağlanır.

İstemci tarafı ihtiyaçları için alternatifler

Coğrafi kodlama gerektiren istemci tarafı ihtiyaçlarınız varsa mevcut istemci tarafı çözümlerinden birini kullanabilirsiniz:

• Maps JavaScript API'deki Geocoding Hizmeti: Geocoding Service, v3 arka ucunu kullanmaya devam eder ve tarayıcı ortamında kullanılmak üzere tasarlanmıştır.
• Places UI Kit: Adresle ilgili kullanıcı arayüzü öğeleri için Yer Otomatik Tamamlama öğeleri dahil olmak üzere Places UI Kit'i kullanın.