Bermigrasi dari Geocoding v3 ke v4

Developer Wilayah Ekonomi Eropa (EEA)

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 Maju 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

Parameter v3 Parameter v4 Catatan
address, components address Alamat tidak terstruktur (v3 address) kini diteruskan di jalur URL. Komponen alamat terstruktur (v3 components) dapat diteruskan sebagai parameter kueri address.*. Lihat Mereproduksi filter komponen v3.
bounds locationBias.rectangle Diganti namanya; struktur diubah menjadi objek.
language languageCode Diganti namanya.
region regionCode Diganti namanya.
extra_computations Dihapus Digantikan oleh metode SearchDestinations.

Perubahan kolom respons

Kolom v3 Kolom v4 Catatan
status, error_message Dihapus v4 menggunakan kode status HTTP dan isi error.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText Diganti namanya.
results.geometry.location_type results.granularity Diganti namanya.
results.geometry.location results.location Nama kolom: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Nama kolom: northeast/southwest -> high/low.
results.postcode_localities results.postalCodeLocalities Diganti namanya. Sekarang ditampilkan untuk satu atau beberapa lokalitas (v3 diperlukan >1).
results.partial_match Dihapus
Baru results.addressComponents.languageCode Bahasa komponen alamat tertentu.
Baru results.bounds Batas eksplisit menggunakan high/low.
Baru results.place Nama resource untuk tempat.
Baru results.postalAddress Objek PostalAddress terstruktur.

Mereproduksi filter komponen v3

Geocoding Maju di Geocoding v3 menyertakan parameter components yang memungkinkan pemfilteran ketat hasil untuk komponen tertentu (misalnya, components=country:US). Geocoding Maju 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 tetap. Sebagai gantinya, semua komponen yang diberikan digabungkan untuk membentuk alamat lengkap yang akan dicoba di-geocode oleh API. API 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 terpisah. Hal ini dapat membantu API menangani kesalahan ketik atau ambiguitas kecil 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:

Filter komponen v3 Kolom respons v4
country postalAddress.regionCode
postal_code postalAddress.postalCode
administrative_area postalAddress.administrativeArea atau addressComponents

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.

Memfilter 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 menampilkannya dalam huruf besar dalam respons, jadi Anda harus menormalisasi input ke huruf besar sebelum perbandingan.

Contoh Kode Python 
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')
Contoh Kode Node.js 
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');
Memfilter 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 sufiks kode ISO 3166-2 karena beberapa alasan. Pertama, di beberapa area, subdivisi yang sesuai dengan kode ISO 3166-2 bukan merupakan 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 sufiks kode ISO 3166-2 subdivisi). Selain itu, subdivisi dalam beberapa kasus dapat ditampilkan di komponen alamat untuk administrative_area_level_n dengan n lebih besar dari 1. Untuk 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).

Contoh Kode Python 
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')
Contoh Kode Node.js 
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');
Memfilter 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 canggih 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 region yang Anda targetkan.

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

Contoh Kode Python (berfokus pada Kode ZIP AS) 
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')
Contoh Kode Node.js (berfokus pada Kode ZIP AS) 
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 v3 Reverse Geocoding untuk mengubah koordinat menjadi alamat, Anda harus bermigrasi ke metode v4 Reverse geocode a location, 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

Parameter v3 Parameter v4 Catatan
language languageCode Diganti namanya.
region regionCode Diganti namanya.
result_type types Diganti namanya; menggunakan parameter kueri berulang.
location_type granularity Diganti namanya; menggunakan parameter kueri berulang.
extra_computations Dihapus Digantikan oleh metode SearchDestinations.

Perubahan kolom respons

Kolom v3 Kolom v4 Catatan
status, error_message Dihapus v4 menggunakan kode status HTTP dan isi error.
results.address_components.long_name / results.address_components.short_name results.addressComponents.longText / results.addressComponents.shortText Diganti namanya.
results.geometry.location_type results.granularity Diganti namanya.
results.geometry.location results.location Nama kolom: lat/lng -> latitude/longitude.
results.geometry.viewport results.viewport Nama kolom: northeast/southwest -> high/low.
Baru results.addressComponents.languageCode Bahasa komponen alamat tertentu.
Baru results.bounds Batas eksplisit menggunakan high/low.
Baru results.place Nama resource untuk tempat.
Baru results.postalAddress Objek PostalAddress terstruktur.

Bermigrasi dari deskriptor Alamat v3

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

Bermigrasi dari geocoding Place v3

Jika Anda menggunakan place_id untuk mendapatkan alamat untuk ID Tempat tertentu dengan Geocoding v3, Anda harus bermigrasi ke metode Place Geocoding 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

Parameter v3 Parameter v4 Catatan
place_id Kolom place dalam proto permintaan ID Tempat kini diberikan sebagai parameter jalur places/{place}, misalnya: https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Hal ini dipetakan ke kolom tempat dalam permintaan yang mendasarinya.
language languageCode Diganti namanya.
region regionCode Diganti namanya.

Perubahan kolom respons

Kolom v3 Kolom v4 Catatan
status, error_message Dihapus v4 menggunakan kode status HTTP dan isi error.
results (root) v4 menampilkan satu objek hasil, bukan array results.
results.address_components.long_name / results.address_components.short_name addressComponents.longText / addressComponents.shortText Diganti namanya.
results.geometry.location_type granularity Diganti namanya.
results.geometry.location location Nama kolom: lat/lng -> latitude/longitude.
results.geometry.viewport viewport Nama kolom: northeast/southwest -> high/low.
results.postcode_localities postalCodeLocalities Diganti namanya. Sekarang ditampilkan untuk satu atau beberapa lokalitas (v3 diperlukan >1).
Baru addressComponents.languageCode Bahasa komponen alamat tertentu.
Baru bounds Batas eksplisit menggunakan high/low.
Baru place Nama resource untuk tempat.
Baru postalAddress Objek PostalAddress terstruktur.

Bermigrasi dari Data Hyperlokal Geocoding ke Tujuan

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 mudah dibaca untuk pintu masuk, misalnya "Gerbang B".
  • location - ini adalah lokasi berjenis LatLng, yang berbeda dengan format yang digunakan di Geocoding API v3.
  • tags - ini sama dengan kolom tags pintu masuk dari Geocoding API v3.
  • place - serupa dengan kolom buildingPlaceId pintu masuk dari Geocoding API v3. Namun, ID Tempat di kolom ini dapat berupa ID Tempat dari jenis apa pun, tidak harus berupa bangunan.

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

Perhatikan bahwa format navigationPoint sedikit berbeda dari 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 berjenis 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 menunjukkan 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. Perhatikan bahwa sebagian besar titik navigasi akan memiliki penggunaan UNKNOWN, tetapi hal itu tidak berarti penggunaan titik navigasi dibatasi dengan cara apa pun.

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 merepresentasikan bangunan.
  • destination.subDestinations - ini adalah kolom berulang yang dapat menyimpan sub-tujuan dari tempat utama. Misalnya, unit apartemen individu dalam sebuah gedung. 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

Mirip dengan pembuatan garis besar, untuk mendapatkan alasan yang terkait dengan destination, Anda harus menggunakan kolom displayPolygon objek placeView dalam destination yang merepresentasikan alasan. 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 alasan 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, yaitu 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 (v4 SearchDestinations), tidak ada kolom location_type. Sebagai gantinya, informasi spasial ditangani secara berbeda:

  • Tidak memerlukan pemfilteran manual di sisi klien: Meskipun Geocoding standar memberikan beberapa hasil dengan perincian yang berbeda, metode SearchDestinations meminimalkan ambiguitas dengan menyelesaikan ke satu tujuan yang dioptimalkan jika memungkinkan. Hal ini menghilangkan kebutuhan klien untuk memfilter menurut jenis lokasi guna menentukan hasil mana yang terbaik.
  • Informasi spasial yang diwakili oleh jenis struktur dan menampilkan poligon: Geometri dan struktur spasial ditunjukkan oleh:
    • displayPolygon (untuk geometri persis).
    • Kolom structureType dalam objek placeView.
  • Pemetaan jenis struktur:
    • structureType dari POINT, BUILDING, atau SECTION umumnya sesuai dengan apa yang disebut ROOFTOP sebelumnya.
    • structureType 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. Mask kolom dapat disetel ke * untuk menampilkan semua kolom, atau Anda dapat menyetelnya 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 area 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.

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: