Bermigrasi dari Geocoding v3 ke v4

Geocoding API v4 memperkenalkan beberapa metode baru yang menggantikan fungsi di API v3. Panduan ini menunjukkan cara memigrasikan aplikasi Anda untuk menggunakan metode v4 baru.

Anda dapat menggunakan kunci API yang ada dengan metode v4 baru. Namun, jika Anda telah meminta peningkatan kuota di API v3, Anda harus meminta peningkatan di API v4 yang baru.

Bermigrasi dari Geocoding Forward v3

Jika Anda menggunakan Geocoding v3 untuk melakukan geocoding alamat, Anda harus bermigrasi ke metode Geocode an address v4, yang menerima permintaan GET.

API v4 mengubah nama, struktur, dan dukungan untuk beberapa parameter. Sebaiknya Anda menggunakan mask kolom untuk menentukan kolom yang ingin ditampilkan dalam respons.

Meminta perubahan parameter

Perubahan kolom respons

Mereproduksi filter komponen v3

Geocoding Forward di Geocoding v3 menyertakan parameter components yang memungkinkan pemfilteran ketat hasil untuk komponen tertentu (misalnya, components=country:US). Geocoding Forward di v4 tidak mendukung jenis pemfilteran ketat ini dalam parameter permintaan. Di v4, Anda dapat memberikan informasi alamat sebagai satu string tidak terstruktur di jalur atau sebagai parameter kueri terstruktur seperti address.addressLines, address.locality, address.administrativeArea, address.postalCode, dan address.regionCode. Parameter terstruktur tidak berfungsi sebagai filter ketat. Sebagai gantinya, semua komponen yang diberikan digabungkan untuk membentuk alamat lengkap yang akan dicoba di-geocode oleh API. API akan menelusuri kecocokan terbaik untuk seluruh alamat yang ditentukan di semua komponen. Menyediakan komponen secara terstruktur dapat membantu API memahami maksud dengan lebih baik, terutama saat informasi alamat dikumpulkan dari kolom formulir yang terpisah. Hal ini dapat membantu API dalam menangani kesalahan ketik kecil atau ambiguitas dalam setiap komponen, karena jenis informasi di setiap kolom sudah jelas.

Untuk mendapatkan perilaku yang mirip dengan filter komponen tetap v3, Anda harus menerapkan pemfilteran sisi klien pada array results yang ditampilkan oleh v4 API berdasarkan objek postalAddress dan addressComponents dalam respons.

Tabel berikut menunjukkan kecocokan terbaik antara filter components v3 dan kolom postalAddress v4:

Contoh pemfilteran sisi klien

Contoh berikut menunjukkan cara memfilter hasil untuk mencapai perilaku yang mirip dengan pemfilteran komponen v3 untuk kolom yang didukung: negara, wilayah administratif, dan kode pos. Sebaiknya jangan memfilter kolom lain karena kriteria pemfilteran yang andal tidak ada.

Filter menurut Negara

Cocokkan address.regionCode dari permintaan Anda dengan postalAddress.regionCode di setiap hasil. Perhatikan bahwa meskipun API menerima kode wilayah huruf kecil dalam permintaan, API selalu menampilkan kode wilayah dalam huruf besar dalam respons, sehingga Anda harus menormalisasi input ke huruf besar sebelum perbandingan.

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');

Filter menurut Wilayah Administratif

Cocokkan address.administrativeArea dari permintaan Anda dengan postalAddress.administrativeArea di setiap hasil. Mirip dengan kode negara, Anda harus menormalisasi input ke huruf besar sebelum perbandingan. Hal ini hanya dapat diandalkan jika administrativeArea dalam permintaan Anda diberikan dengan singkatan 2 huruf standar. postalAddress.administrativeArea dalam respons mungkin tidak langsung cocok dengan akhiran kode ISO 3166-2 karena beberapa alasan. Pertama, di beberapa area, subdivisi yang sesuai dengan kode ISO 3166-2 bukan bagian dari representasi standar alamat pos. Misalnya, di Spanyol, area administratif level 1 (misalnya, "CN" untuk Canarias) mungkin ada di addressComponents, tetapi postalAddress.administrativeArea mungkin berisi area level 2 (misalnya, "Santa Cruz de Tenerife"). Kedua, di beberapa area, singkatan subdivisi tidak umum digunakan dan ditampilkan di postalAddress.administrativeArea dengan nama yang lebih panjang (untuk alasan serupa, addressComponents.shortText untuk komponen alamat yang sesuai dengan subdivisi mungkin tidak cocok dengan akhiran kode ISO 3166-2 subdivisi). Selain itu, sub-divisi dalam beberapa kasus dapat ditampilkan di komponen alamat untuk administrative_area_level_n dengan n lebih besar dari 1. Untuk mendapatkan hasil yang paling komprehensif, Anda harus memeriksa kecocokan di postalAddress.administrativeArea dan addressComponents apa pun dengan jenis administrative_area_level_n (misalnya, administrative_area_level_1).

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');

Filter menurut Kode Pos

Cocokkan address.postalCode dari permintaan Anda dengan postalAddress.postalCode di setiap hasil. Anda harus menormalisasi kode pos input dan hasil sebelum perbandingan. Logika normalisasi sangat bergantung pada wilayah. Pendekatan dasar melibatkan penghapusan spasi dan tanda hubung serta konversi ke huruf yang konsisten.

Normalisasi yang lebih lanjut mungkin diperlukan untuk menangani awalan kode pos (misalnya, "L2" di Inggris Raya) atau akhiran (misalnya, "+4" di kode pos AS). Logika normalisasi spesifik yang diperlukan akan bervariasi, bergantung pada negara dan format kode pos yang terlibat. Anda mungkin perlu menyesuaikan fungsi normalisasi yang disediakan atau menerapkan logika yang lebih canggih untuk wilayah yang Anda targetkan.

Contoh yang diberikan menangani kode pos AS dan memungkinkan pencocokan pada basis 5 digit meskipun ZIP+4 diberikan atau ditampilkan.

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');

Bermigrasi dari Geocoding Terbalik v3

Jika Anda menggunakan Geocoding Terbalik v3 untuk mengubah koordinat menjadi alamat, Anda harus bermigrasi ke metode Geocoding terbalik lokasi v4, yang menerima permintaan GET.

API v4 mengubah nama, struktur, dan dukungan untuk beberapa parameter. Sebaiknya Anda menggunakan mask kolom untuk menentukan kolom yang ingin ditampilkan dalam respons.

Meminta perubahan parameter

Perubahan kolom respons

Bermigrasi dari Deskripsi alamat v3

Jika Anda menggunakan address_descriptor untuk mendapatkan informasi tambahan tentang lokasi dengan Geocoding v3, Anda harus bermigrasi untuk menggunakan kolom landmarks dari SearchDestinationsResponse.

Bermigrasi dari geocoding Place v3

Jika Anda menggunakan place_id untuk mendapatkan alamat ID Tempat tertentu dengan Geocoding v3, Anda harus bermigrasi ke metode Geocoding Tempat v4, yang menerima permintaan GET.

API v4 mengubah nama, struktur, dan dukungan untuk beberapa parameter. Sebaiknya Anda menggunakan mask kolom untuk menentukan kolom yang ingin ditampilkan dalam respons.

Meminta perubahan parameter

Perubahan kolom respons

Bermigrasi dari Data Hiperlokal Geocoding ke Destinations

Fitur berikut di Geocoding API v3 digantikan oleh metode SearchDestinations Geocoding API v4:

• Masuk
• Titik navigasi
• Garis batas bangunan
• Area

Jika Anda menggunakan Geocoding API v3 untuk fitur di atas, gunakan dokumen ini untuk membantu Anda menggunakan metode SearchDestinations sebagai gantinya untuk mendapatkan fitur ini. Dokumen ini menjelaskan lokasi fitur ini dalam respons SearchDestinations, dan perbedaan cara fitur ini ditampilkan dalam respons API antara Geocoding API v3 dan metode SearchDestinations Geocoding API v4.

Masuk

Untuk mendapatkan pintu masuk yang terkait dengan destination, gunakan kolom destination.entrances.

Perhatikan bahwa format entrance sedikit berbeda dari format entri di Geocoding API v3. Setiap pintu masuk di destination.entrances memiliki kolom berikut:

• displayName - ini adalah kolom opsional baru yang akan memiliki nama yang dapat dibaca manusia untuk pintu masuk, misalnya "Gerbang B".
• location - ini adalah lokasi jenis LatLng, yang berbeda dengan format yang digunakan di Geocoding API v3.
• tags - ini sama dengan kolom tags pintu masuk dari Geocoding API v3.
• place - analog dengan kolom buildingPlaceId untuk pintu masuk dari Geocoding API v3. Namun, ID Tempat di kolom ini dapat berupa Tempat dari jenis apa pun, tidak harus berupa bangunan.

Titik navigasi

Untuk mendapatkan titik navigasi yang terkait dengan destination, gunakan kolom destination.navigationPoints.

Perhatikan bahwa format navigationPoint sedikit berbeda dengan format titik navigasi di Geocoding API v3. Setiap titik navigasi di destination.navigationPoints memiliki kolom berikut:

• displayName - ini adalah kolom opsional baru yang akan memiliki nama yang dapat dibaca manusia untuk titik navigasi, misalnya "5th Ave".
• location - ini adalah lokasi jenis LatLng, yang berbeda dengan format yang digunakan di Geocoding API v3.
• travelModes - ini mirip dengan kolom restrictedTravelModes dari titik navigasi dari Geocoding API v3. Nilai enum yang mungkin sama, satu-satunya perbedaan adalah kolom ini sekarang mewakili mode perjalanan yang dapat diterima untuk titik navigasi, bukan mode perjalanan yang dibatasi.
• usage - ini adalah kolom baru yang berisi kasus penggunaan yang didukung oleh titik navigasi.

Garis batas bangunan

Untuk mendapatkan garis batas bangunan yang terkait dengan destination, Anda harus menggunakan kolom displayPolygon dari objek placeView di destination yang merepresentasikan bangunan. Untuk setiap placeView, Anda dapat memeriksa apakah itu adalah bangunan dengan kolom placeView.structureType. Jika jenis struktur adalah BUILDING, Anda bisa mendapatkan garis batas dari kolom placeView.displayPolygon. placeView juga akan memiliki kolom tambahan untuk bangunan yang tidak ada di Geocoding API v3.

destination dapat memiliki objek placeView yang merepresentasikan bangunan di kolom berikut:

• destination.primary - ini adalah tempat utama untuk tujuan.
• destination.containingPlaces - ini adalah kolom berulang yang dapat menyimpan tempat yang lebih besar yang "berisi" tempat utama. Misalnya, jika tempat utama adalah subpremise, containingPlaces biasanya akan menyimpan placeView yang mewakili bangunan.
• destination.subDestinations - ini adalah kolom berulang yang dapat menyimpan sub-tujuan dari tempat utama. Misalnya, unit apartemen individual dari sebuah bangunan. Kolom ini biasanya tidak memiliki placeView yang merepresentasikan bangunan.

Perhatikan bahwa format placeView.displayPolygon cocok dengan format outline bangunan di Geocoding API v3, yaitu format GeoJSON, menggunakan format RFC 7946.

Area

Serupa dengan garis batas bangunan, untuk mendapatkan halaman yang terkait dengan destination, Anda harus menggunakan kolom displayPolygon dari objek placeView di destination yang mewakili halaman. Untuk setiap placeView, Anda dapat memeriksa apakah itu adalah alasan dengan kolom placeView.structureType. Jika jenis struktur adalah GROUNDS, Anda bisa mendapatkan garis besarnya dari kolom placeView.displayPolygon. placeView juga akan memiliki kolom tambahan untuk dasar yang tidak ada di Geocoding API v3.

destination dapat memiliki objek placeView yang merepresentasikan alasan dalam kolom berikut:

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

Perhatikan bahwa format placeView.displayPolygon cocok dengan format garis batas lapangan di Geocoding API v3, yang merupakan format GeoJSON, menggunakan format RFC 7946.

Presisi hasil

Di Geocoding API v3, kolom location_type dalam geometri respons menunjukkan presisi hasil, dan beberapa klien akan memberi peringkat atau memfilter hasil berdasarkan nilai ini (ROOFTOP, RANGE_INTERPOLATED, GEOMETRIC_CENTER, dan APPROXIMATE). Dalam migrasi Geocoding API v4 standar, kolom ini diganti namanya menjadi granularity.

Di Destinations API (SearchDestinations v4), tidak ada kolom location_type. Sebagai gantinya, informasi spasial ditangani secara berbeda:

• Tidak memerlukan pemfilteran manual sisi klien: Meskipun Geocoding standar memberikan beberapa hasil di berbagai tingkat perincian, metode SearchDestinations meminimalkan ambiguitas dengan memberikan satu tujuan yang dioptimalkan jika memungkinkan. Hal ini menghilangkan kebutuhan klien untuk memfilter menurut jenis lokasi guna menentukan hasil terbaik.
• Informasi spasial yang diwakili oleh jenis struktur dan poligon tampilan: Geometri dan struktur spasial ditunjukkan oleh:
  • displayPolygon (untuk geometri yang tepat).
  • Kolom structureType dalam objek placeView.
• Pemetaan jenis struktur:
  • structureType dari POINT, BUILDING, atau SECTION umumnya sesuai dengan yang sebelumnya disebut ROOFTOP.
  • structureType dari GROUNDS umumnya sesuai dengan GEOMETRIC_CENTER.

Menggunakan mask kolom untuk meminta fitur ini

Metode SearchDestinations memerlukan mask kolom, seperti yang dijelaskan dalam Memilih kolom yang akan ditampilkan. Masker kolom dapat ditetapkan ke * untuk menampilkan semua kolom, atau Anda dapat menetapkannya ke kolom tertentu yang ingin Anda terima. Misalnya, permintaan API berikut menetapkan mask kolom untuk menerima semua kolom yang diperlukan guna mendapatkan pintu masuk, titik navigasi, garis batas bangunan, dan halaman tujuan:

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

Pertimbangan keamanan

Geocoding API v4 didesain sebagai API server-ke-server. Tidak ada jalur migrasi langsung untuk pengguna JavaScript dari v3 ke v4. Memanggil metode v4 langsung dari JavaScript sisi klien (misalnya, di browser) menggunakan kunci API membuat kunci API Anda berisiko tinggi dicuri dan disalahgunakan.

Pembatasan perujuk HTTP, meskipun berguna, tidak memberikan perlindungan yang memadai untuk endpoint layanan web karena dapat dengan mudah dilewati oleh penyerang yang memalsukan header Referer dalam permintaan mereka.

Pendekatan yang direkomendasikan

Cara yang direkomendasikan untuk menggunakan Geocoding API v4 adalah dari server backend Anda sendiri. Aplikasi klien Anda harus membuat permintaan ke server perantara ini, yang kemudian memanggil Google API secara aman menggunakan kunci API yang dilindungi (misalnya, kunci yang disimpan dalam variabel lingkungan atau secret manager). Hal ini memastikan bahwa kunci API Anda tidak pernah diekspos dalam kode frontend.

Alternatif untuk kebutuhan sisi klien

Jika Anda memiliki kebutuhan sisi klien yang memerlukan geocoding, pertimbangkan untuk menggunakan salah satu solusi sisi klien yang ada:

• Geocoding Service di Maps JavaScript API: Geocoding Service terus menggunakan backend v3 dan dirancang untuk digunakan di lingkungan browser.
• Kit UI Places: Gunakan Kit UI Places, termasuk elemen Place Autocomplete, untuk elemen antarmuka pengguna terkait alamat.