Bermigrasi dari Geocoding v3 ke v4

Developer Wilayah Ekonomi Eropa (EEA)

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.

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.

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.

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.

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.

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.

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