Bermigrasi dari Geocoding v3 ke v4

Developer Wilayah Ekonomi Eropa (EEA)

Jika alamat penagihan Anda berada di Wilayah Ekonomi Eropa, mulai 8 Juli 2025, Persyaratan Layanan Google Maps Platform EEA akan berlaku untuk penggunaan Layanan oleh Anda. Fungsi bervariasi menurut wilayah. Pelajari lebih lanjut.

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

Anda dapat menggunakan kunci API yang ada dengan endpoint v4 baru. Namun, jika Anda telah meminta peningkatan kuota di API v3, Anda harus meminta peningkatan di API v4 yang baru. Tidak ada jalur migrasi untuk pengguna JavaScript.

Catatan: Selama Pratinjau, metode Geocoding API v4 dibatasi hingga 25 kueri per detik (QPS). Untuk mengetahui informasi tentang cara meminta kuota yang lebih tinggi, lihat Melihat dan mengelola kuota, lalu pilih Geocoding API sebagai layanan.

Bermigrasi dari Geocoding Maju v3

Jika Anda menggunakan Geocoding untuk membuat geocode alamat, Anda harus bermigrasi ke endpoint Geocode alamat 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.

Peringatan: Di semua endpoint v4, nama kolom diformat menggunakan lower camel case (misalnya, addressComponents), berbeda dengan endpoint v3, yang menggunakan snake case (misalnya, address_components). Respons RPC terus menggunakan snake case di v4, seperti di v3.

Meminta perubahan parameter

Parameter v3	Parameter v4	Catatan
address, components	address	Alamat tidak terstruktur (v3 address) kini diteruskan di jalur URL. Filter komponen (v3 components) kini diteruskan sebagai parameter kueri address.*.
bounds	locationBias.rectangle	Diganti namanya; struktur diubah menjadi objek.
language	languageCode	Diganti namanya.
region	regionCode	Diganti namanya.
extra_computations	Dihapus

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.

Bermigrasi dari Geocoding Terbalik v3

Jika Anda menggunakan Reverse Geocoding untuk mengubah koordinat menjadi alamat, Anda harus bermigrasi ke endpoint 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.

Peringatan: Di semua endpoint v4, nama kolom diformat menggunakan lower camel case (misalnya, addressComponents), berbeda dengan endpoint v3, yang menggunakan snake case (misalnya, address_components). Respons RPC terus menggunakan snake case di v4, seperti di v3.

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

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 Geocoding Tempat v3

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

Peringatan: Di semua endpoint v4, nama kolom diformat menggunakan lower camel case (misalnya, addressComponents), berbeda dengan endpoint v3, yang menggunakan snake case (misalnya, address_components). Respons RPC terus menggunakan snake case di v4, seperti di v3.

Meminta perubahan parameter

Parameter v3	Parameter v4	Catatan
place_id	Kolom place di proto permintaan	ID Tempat kini diberikan sebagai parameter jalur places/{place}, misalnya: https://geocode.googleapis.com/v4beta/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 endpoint SearchDestinations Geocoding API v4:

• Masuk
• Titik navigasi
• Membuat kerangka
• Area

Jika Anda menggunakan Geocoding API v3 untuk fitur di atas, gunakan dokumen ini untuk membantu Anda menggunakan endpoint SearchDestinations sebagai gantinya untuk mendapatkan fitur ini. Dokumen ini menjelaskan lokasi fitur ini dalam respons SearchDestinations API, dan perbedaan cara fitur ini ditampilkan dalam respons API antara Geocoding API v3 dan endpoint SearchDestinations dari 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 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 - analog 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.

Titik navigasi

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.

Membuat kerangka

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.

Catatan: Hanya mencari poligon bangunan di lokasi tertentu? Anda dapat menggunakan parameter placeFilter dalam permintaan untuk mempersempit hasil. Untuk hanya menampilkan hasil bangunan, tetapkan structureType ke "BUILDING" dalam placeFilter. Jika mendapatkan poligon adalah prioritas Anda (bahkan untuk lokasi tanpa alamat yang akurat), tetapkan addressability ke "ANY" di placeFilter untuk menampilkan poligon paling akurat yang tersedia.

Contoh

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

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 membuat garis besar, untuk mendapatkan alasan yang terkait dengan destination, Anda harus menggunakan kolom displayPolygon dari 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 wilayah dalam Geocoding API v3, yaitu format GeoJSON, menggunakan format RFC 7946.

Menggunakan mask kolom untuk meminta fitur ini

Endpoint 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/v4alpha/geocode/destinations