Geocoding v3'ten v4'e geçiş

Coğrafi Kodlama API'si 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 v3 sürümünde kota artışı istediyseniz yeni v4 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ç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.

İstek parametresi değişiklikleri

Yanıt alanı değişiklikleri

V3 bileşen filtrelerini yeniden oluşturma

Geocoding v3'teki ileriye doğru coğrafi kodlama, belirli bileşenler (ör. components=country:US) için sonuçların katı bir şekilde filtrelenmesini sağlayan bir components parametresi içeriyordu. v4'teki ileriye doğru coğrafi kodlama, istek parametrelerinde bu tür katı 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, katı filtreler 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. Bu, her alandaki bilgi türü net olduğundan 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'nin döndürdüğü 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, bağlı olduğu yer 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 filtrele

Talebinizdeki address.regionCode ile her sonuçtaki postalAddress.regionCode eşleşmelidir. 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');

Bağlı olduğu yere göre filtreleme

Talebinizdeki address.administrativeArea ile her sonuçtaki postalAddress.administrativeArea öğesini eşleştirin. Ülke kodlarında olduğu gibi, karşılaştırmadan önce girişinizi büyük harfe normalleştirmeniz gerekir. Bu, yalnızca isteğinizdeki administrativeArea standart 2 harfli bir kısaltmayla sağlandığında güvenilirdir. Yanıttaki postalAddress.administrativeArea, çeşitli nedenlerle ISO 3166-2 kod son ekleriyle doğrudan eşleşmeyebilir. İlk olarak, 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 1.seviye bağlı olduğu yer (ör. Canarias için "CN") addressComponents içinde bulunabilir ancak postalAddress.administrativeArea, 2.seviye bağlı olduğu yeri (ör. "Santa Cruz de Tenerife") içerebilir. İkincisi, 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) olan tüm 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 eşleşmelidir. Karşılaştırma yapmadan önce hem giriş hem de sonuç posta kodlarını normalleştirmeniz gerekir. Normalleştirme mantığı büyük ölçüde bölgeye bağlıdır. Temel bir yaklaşım, boşlukları ve kısa çizgileri kaldırmayı ve tutarlı bir büyük/küçük harf düzenine dönüştürmeyi içerir.

Posta kodu ön eklerini (ör. Birleşik Krallık'ta "L2") veya son eklerini (ör. ABD posta kodlarında "+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.

Verilen örnek, ABD posta kodlarını işler ve ZIP+4 sağlanmış veya döndürülmüş olsa bile 5 haneli tabanda 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ş yapma

Koordinatları adreslere dönüştürmek için v3 Tersine Coğrafi Kodlama'yı kullanıyorsanız GET isteğini kabul eden v4 Bir konumun tersine coğrafi kodlamasını yapma yöntemine geçmeniz gerekir.

V4 API, çeşitli parametrelerin adlarını, yapısını ve desteğini değiştirir. Yanıtta 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

Geocoding v3 ile bir konum hakkında ek bilgi almak için address_descriptor kullanıyorsanız SearchDestinationsResponse'nin landmarks alanını kullanmaya geçmeniz gerekir.

v3 Yer coğrafi kodlamadan taşıma

Geocoding v3 ile belirli bir yer kimliğinin adresini almak için place_id kullanıyorsanız GET isteği 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ıtta 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 Yakın Çevreye Özel Verilerinden Hedeflere Geçiş

Geocoding API v3'teki aşağıdaki özellikler, Geocoding API v4'ün SearchDestinations yöntemiyle değiştiriliyor:

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

Yukarıdaki özellikler için Geocoding API v3'ü kullanıyorsanız bu özelliklere erişmek 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 bu özelliklerin Geocoding API v3 ile Geocoding API v4'ün SearchDestinations yöntemi arasındaki API yanıtlarında nasıl temsil edildiğiyle ilgili farklılıklar açıklanmaktadır.

Giriş sayısı

Bir 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ş aşağıdaki alanlara sahiptir:

• displayName: Bu, giriş için insan tarafından okunabilir bir ada sahip olacak yeni bir isteğe bağlı alandır (ör. "B Kapısı").
• 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'ten gelen girişlerin tags alanıyla aynıdır.
• place: Geocoding API v3'teki girişlerin buildingPlaceId alanına benzer. Ancak bu alandaki yer kimliği, yalnızca bir bina için değil, herhangi bir türdeki yer için olabilir.

Gezinme noktaları

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 navigasyon noktasında aşağıdaki alanlar bulunur:

• displayName: Bu, gezinme noktasının insan tarafından okunabilir bir adının olacağı yeni bir isteğe bağlı alandır. Örneğin, "5th Ave".
• location: Bu, LatLng türünde bir konumdur. Bu biçim, 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.

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.

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

• destination.primary: Bu, varış noktasının birincil yeridir.
• 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 değerini içerir.
• destination.subDestinations: Bu, birincil yerin alt hedeflerini barındırabilen yinelenen bir alandır. Örneğin, bir binanın ayrı apartman daireleri. Bu alanda genellikle bir binayı temsil eden placeView bulunmaz.

placeView.displayPolygon biçiminin, Geocoding API v3'teki bina ana hattı biçimiyle eşleştiğini unutmayın. Bu biçim, RFC 7946 biçimini kullanan GeoJSON biçimidir.

Saha

Bina ana hatlarına benzer şekilde, bir destination ile ilişkili arazileri almak için destination içindeki placeView nesnelerinin displayPolygon alanını kullanmanız gerekir. Her placeView için placeView.structureType alanını kullanarak bunun bir gerekçe olup olmadığını kontrol edebilirsiniz. Yapı türü GROUNDS ise taslağı 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ıt geometrisindeki location_type alanı sonuçların doğruluğunu gösteriyordu 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ılır.

Hedefler API'sinde (v4 SearchDestinations) location_type alanı yoktur. Bunun yerine, uzamsal 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ü poligonlarıyla temsil edilen mekansal bilgiler: Mekansal geometri ve yapı şunlarla gösterilir:
  • displayPolygon (tam geometri için).
  • placeView nesnesindeki structureType alanı.
• Yapı türü eşleme:
  • POINT, BUILDING veya SECTION structureType değeri genellikle daha önce ROOFTOP olarak adlandırılan değere karşılık gelir.
  • GROUNDS cinsinden structureType, genellikle GEOMETRIC_CENTER cinsinden bir değere karşılık gelir.

Bu özellikleri istemek için alan maskesi kullanma

SearchDestinations yöntemi, Döndürülecek alanları seçme bölümünde açıklandığı gibi bir alan maskesi gerektirir. Alan maskesi, tüm alanları döndürmek için * olarak ayarlanabilir veya almak istediğiniz belirli alanlara ayarlayabilirsiniz. Örneğin, aşağıdaki API isteği, bir hedefin girişlerini, navigasyon noktalarını, bina ana hatlarını ve alanlarını almak için gereken tüm alanları almak üzere 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ü saldırganlar, isteklerinde Referer başlığını taklit ederek bu kısıtlamaları kolayca atlatabilir.

Önerilen yaklaşım

Geocoding API v4'ü kullanmanın önerilen yolu, kendi arka uç sunucunuzdur. İstemci uygulamanız bu aracı sunucuya istekte bulunmalıdır. Bu sunucu daha sonra, korumalı bir API anahtarı (ör. bir ortam değişkeninde veya Secret Manager içinde depolanan bir anahtar) kullanarak Google API'yi güvenli bir şekilde çağırır. Bu sayede API anahtarınız, ön uç kodunda hiçbir zaman görünmez.

İ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 Adı Otomatik Tamamlama öğeleri dahil olmak üzere Places UI Kit'i kullanın.