Layanan Geocoding

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Ringkasan

Geocoding adalah proses konversi alamat (seperti "1600 Amphitheatre Parkway, Mountain View, CA") menjadi koordinat geografis (seperti lintang 37,423021 dan bujur -122,083739), yang dapat Anda gunakan untuk menempatkan penanda atau memosisikan peta.

Geocoding terbalik adalah proses mengonversi koordinat geografis menjadi alamat yang dapat dibaca manusia (lihat Geocoding terbalik (Pencarian Alamat)).

Anda juga dapat menggunakan geocoder untuk menemukan alamat ID tempat tertentu.

Maps JavaScript API menyediakan class Geocoder untuk geocoding dan geocoding terbalik dari input pengguna secara dinamis. Jika Anda ingin melakukan geocoding terhadap alamat statis yang dikenal, lihat layanan web Geocoding.

Memulai

Sebelum menggunakan layanan Geocoding di Maps JavaScript API, pastikan terlebih dahulu bahwa Geocoding API diaktifkan di Google Cloud Console, dalam project yang sama dengan yang Anda siapkan untuk Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

  1. Buka Google Cloud Console.
  2. Klik tombol Select a project, lalu pilih project yang sama dengan yang Anda siapkan untuk Maps JavaScript API dan klik Open.
  3. Dari daftar API di Dasbor, cari Geocoding API.
  4. Jika sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak tercantum, aktifkan:
    1. Di bagian atas halaman, pilih ENABLE API untuk menampilkan tab Library. Atau, dari menu samping kiri, pilih Library.
    2. Telusuri Geocoding API, lalu pilih dari daftar hasil.
    3. Pilih AKTIFKAN. Setelah proses selesai, Geocoding API akan muncul dalam daftar API di Dashboard.

Harga dan kebijakan

Harga

Mulai 16 Juli 2018, paket harga baru, yaitu bayar sesuai penggunaan, diberlakukan untuk Maps, Rute, dan Tempat. Untuk mempelajari lebih lanjut tentang harga dan batas penggunaan baru untuk penggunaan layanan Geocoding JavaScript, lihat Penggunaan dan Penagihan untuk Geocoding API.

Batas kapasitas

Perhatikan hal-hal berikut tentang batas kapasitas pada permintaan tambahan:

Batas kapasitas tambahan diterapkan per sesi pengguna, berapa pun banyaknya pengguna yang berbagi project yang sama. Saat pertama kali memuat API, Anda diberi kuota awal permintaan. Setelah Anda menggunakan kuota ini, API akan menerapkan batas kapasitas pada permintaan tambahan per detik. Jika terlalu banyak permintaan dibuat dalam jangka waktu tertentu, API akan menampilkan kode respons OVER_QUERY_LIMIT.

Batas kecepatan per sesi mencegah penggunaan layanan sisi klien untuk permintaan batch, seperti geocoding batch. Untuk permintaan batch, gunakan layanan web Geocoding API.

Kebijakan

Penggunaan layanan Geocoding harus sesuai dengan kebijakan yang dijelaskan untuk Geocoding API.

Permintaan Geocoding

Mengakses layanan Geocoding bersifat asinkron, karena Google Maps API harus melakukan panggilan ke server eksternal. Karena alasan tersebut, Anda harus meneruskan metode callback untuk dieksekusi setelah permintaan selesai. Metode callback ini memproses hasil. Perhatikan bahwa geocoder mungkin menampilkan lebih dari satu hasil.

Anda mengakses layanan geocoding Google Maps API dalam kode Anda melalui objek konstruktor google.maps.Geocoder. Metode Geocoder.geocode() memulai permintaan ke layanan geocoding, meneruskan literal objek GeocoderRequest yang berisi istilah input dan metode callback yang akan dieksekusi setelah menerima respons.

Literal objek GeocoderRequest berisi kolom berikut:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Parameter yang diperlukan: Anda harus menyediakan satu, dan hanya satu, dari kolom berikut:

  • address — Alamat yang ingin Anda geocoding.
    atau
    locationLatLng (atau LatLngLiteral) yang ingin Anda dapatkan alamat terdekat yang dapat dibaca manusia. Geocoder akan melakukan geocoding terbalik. Lihat Geocoding Terbalik untuk informasi selengkapnya.
    atau
    placeId — ID tempat yang Anda inginkan untuk mendapatkan alamat terdekat yang dapat dibaca manusia. Lihat selengkapnya tentang mengambil alamat untuk ID tempat.

Parameter opsional:

  • boundsLatLngBounds yang akan digunakan untuk mencondongkan hasil geocode secara lebih jelas. Parameter bounds hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. Lihat informasi selengkapnya tentang biasing area pandang di bawah ini.
  • componentRestrictions — Digunakan untuk membatasi hasil ke area tertentu. Lihat informasi selengkapnya tentang pemfilteran komponen di bawah.
  • region — Kode wilayah yang ditentukan sebagai yang ditetapkan sebagai subtag wilayah Unicode dua karakter (non-numerik). Pada umumnya, tag ini dipetakan langsung ke nilai dua karakter ccTLD ("domain level teratas&quot);. Parameter region hanya akan memengaruhi, tidak sepenuhnya membatasi, hasil dari geocoder. Lihat informasi selengkapnya tentang bias kode wilayah di bawah.

Respons Geocoding

Layanan Geocoding memerlukan metode callback yang akan dieksekusi pada saat pengambilan hasil geocoder. Callback ini harus meneruskan dua parameter untuk menyimpan kode results dan kode status dalam urutan tersebut.

Hasil Geocoding

Objek GeocoderResult mewakili satu hasil geocoding. Permintaan geocode mungkin mengembalikan beberapa objek hasil:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Bidang-bidang ini dijelaskan di bawah:

  • types[] adalah array yang menunjukkan jenis alamat hasil yang ditampilkan. Array ini berisi sekumpulan tag nol atau lebih yang mengidentifikasi jenis fitur yang ditampilkan dalam hasil. Misalnya, geocoding "Chicago" menampilkan "lokalitas" yang menunjukkan bahwa "Chicago" adalah kota, dan juga menampilkan "politik" yang menunjukkan bahwa itu adalah entitas politik. Lihat informasi selengkapnya tentang jenis alamat dan jenis komponen alamat di bawah.
  • formatted_address adalah string yang berisi alamat lokasi ini yang dapat dibaca manusia.

    Sering kali alamat ini sama dengan alamat pos. Perhatikan bahwa beberapa negara, seperti Inggris Raya, tidak mengizinkan distribusi alamat pos sebenarnya karena adanya pembatasan pemberian lisensi.

    Alamat yang diformat secara logis terdiri dari satu atau beberapa komponen alamat. Misalnya, alamat "111 8th Avenue, New York, NY" terdiri dari komponen berikut: "111" (nomor jalan), "8th Avenue" (rute), "New York" (kota) dan "NY" (negara bagian AS).

    Jangan mengurai alamat berformat secara terprogram. Sebagai gantinya, Anda harus menggunakan komponen alamat individual, yang disertakan oleh respons API selain kolom alamat yang diformat.

  • address_components[] adalah array yang berisi komponen terpisah yang berlaku untuk alamat ini.

    Setiap komponen alamat biasanya berisi kolom berikut:

    • types[] adalah array yang menunjukkan jenis komponen alamat. Lihat daftar jenis yang didukung.
    • long_name adalah deskripsi teks lengkap atau nama komponen alamat seperti yang ditampilkan oleh Geocoder.
    • short_name adalah nama tekstual yang disingkat untuk komponen alamat, jika tersedia. Misalnya, komponen alamat untuk negara bagian Alaska dapat memiliki long_name "Alaska" dan short_name dari "AK" menggunakan singkatan pos 2 huruf.

    Perhatikan fakta berikut tentang array address_components[]:

    • Array komponen alamat dapat berisi lebih banyak komponen daripada formatted_address.
    • Array tidak harus menyertakan semua entity politik yang berisi alamat, selain dari yang disertakan dalam formatted_address. Untuk mengambil semua entitas politik yang berisi alamat tertentu, Anda harus menggunakan geocoding terbalik, dengan meneruskan garis lintang/bujur alamat sebagai parameter ke permintaan tersebut.
    • Format respons tidak dijamin tetap sama di antara permintaan. Secara khusus, jumlah address_components bervariasi berdasarkan alamat yang diminta dan dapat berubah dari waktu ke waktu untuk alamat yang sama. Komponen dapat mengubah posisi di array. Jenis komponen dapat berubah. Komponen tertentu mungkin tidak ada dalam respons berikutnya.

    Lihat informasi selengkapnya tentang jenis alamat dan jenis komponen alamat di bawah.

  • partial_match menunjukkan bahwa geocoder tidak menampilkan hasil yang sama persis dengan permintaan asli, meskipun dapat mencocokkan bagian dari alamat yang diminta. Anda dapat memeriksa permintaan asli untuk kesalahan ejaan dan/atau alamat yang tidak lengkap.

    Kecocokan parsial paling sering terjadi untuk alamat yang tidak ada dalam lokalitas yang Anda teruskan dalam permintaan. Kecocokan parsial juga dapat ditampilkan jika permintaan cocok dengan dua lokasi atau lebih dalam lokalitas yang sama. Misalnya, "Hillpar St, Bristol, UK" akan menampilkan kecocokan parsial untuk Henry Street dan Henrietta Street. Perhatikan bahwa jika permintaan menyertakan komponen alamat yang salah eja, layanan geocoding mungkin akan menyarankan alamat alternatif. Saran yang dipicu dengan cara ini juga akan ditandai sebagai kecocokan sebagian.

  • place_id adalah ID unik suatu tempat, yang dapat digunakan dengan Google API lainnya. Misalnya, Anda dapat menggunakan place_id dengan library Google Places API untuk mendapatkan detail bisnis lokal, seperti nomor telepon, jam buka, ulasan pengguna, dan lainnya. Lihat ringkasan ID tempat.
  • postcode_localities[] adalah array yang menunjukkan semua lokalitas yang terdapat dalam kode pos, dan hanya ada jika hasilnya adalah kode pos yang berisi beberapa lokalitas.
  • geometry berisi informasi berikut:

    • location berisi nilai lintang dan bujur yang di-geocoding. Perhatikan bahwa kami menampilkan lokasi ini sebagai objek LatLng, bukan sebagai string yang diformat.
    • location_type menyimpan data tambahan tentang lokasi yang ditentukan. Nilai-nilai berikut saat ini didukung:
      • ROOFTOP menunjukkan bahwa hasil yang ditampilkan mencerminkan geocode akurat.
      • RANGE_INTERPOLATED menunjukkan bahwa hasil yang ditampilkan mencerminkan perkiraan (biasanya di jalan) interpolasi antara dua titik akurat (seperti persimpangan). Hasil interpolasi umumnya ditampilkan jika geocode rooftop tidak tersedia untuk alamat jalan.
      • GEOMETRIC_CENTER menunjukkan bahwa hasil yang ditampilkan adalah pusat geometris dari hasil seperti polyline (misalnya, jalan) atau poligon (region).
      • APPROXIMATE menunjukkan bahwa hasil yang ditampilkan adalah perkiraan.

    • viewport menyimpan area pandang yang direkomendasikan untuk hasil yang ditampilkan.
    • bounds (opsional ditampilkan) menyimpan LatLngBounds yang dapat sepenuhnya berisi hasil yang ditampilkan. Perhatikan, batas-batas ini mungkin tidak cocok dengan tampilan yang terlihat yang disarankan. (Misalnya, San Francisco menyertakan Farallon Islands, yang secara teknis merupakan bagian dari kota, tetapi tidak boleh ditampilkan di area pandang.)

Alamat akan ditampilkan oleh Geocoder menggunakan setelan bahasa pilihan browser, atau bahasa yang ditentukan saat memuat JavaScript API menggunakan parameter language. (Untuk informasi selengkapnya, lihat Pelokalan.)

Tipe Alamat dan Tipe Komponen Alamat

Array types[] dalam GeocoderResult menunjukkan jenis alamat. Array types[] juga dapat ditampilkan dalam GeocoderAddressComponent untuk menunjukkan jenis komponen alamat tertentu. Alamat yang ditampilkan oleh geocoder mungkin memiliki beberapa jenis; jenis dapat dianggap sebagai tag. Misalnya, banyak kota diberi tag dengan jenis political dan locality.

Jenis berikut didukung dan ditampilkan oleh geocoder dalam jenis alamat dan jenis komponen alamat:

  • street_address menunjukkan alamat yang akurat.
  • route menunjukkan rute yang dinamai (seperti "US 101").
  • intersection menunjukkan persimpangan utama, yang biasanya terdiri dari dua jalan utama.
  • political menunjukkan entitas politik. Biasanya, jenis ini menunjukkan poligon dari beberapa pemerintahan sipil.
  • country menunjukkan entitas politik nasional, dan biasanya merupakan jenis pesanan tertinggi yang ditampilkan oleh Geocoder.
  • administrative_area_level_1 menunjukkan entitas sipil urutan pertama di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah negara bagian. Tidak semua negara menampilkan tingkat administratif ini. Dalam kebanyakan kasus, nama pendek admin_area_level_1 akan sangat cocok dengan subdivisi ISO 3166-2 dan daftar lainnya yang beredar luas; tetapi ini tidak dijamin karena hasil geocoding kami didasarkan pada berbagai sinyal dan data lokasi.
  • administrative_area_level_2 menunjukkan entitas sipil urutan kedua di bawah tingkat negara. Di Amerika Serikat, tingkat administratif ini adalah county. Tidak semua negara menampilkan tingkat administratif ini.
  • administrative_area_level_3 menunjukkan entitas sipil urutan ketiga di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_4 menunjukkan entitas sipil urutan keempat di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_5 menunjukkan entitas sipil urutan kelima di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_6 menunjukkan entitas sipil urutan keenam di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • administrative_area_level_7 menunjukkan entitas sipil urutan ketujuh di bawah tingkat negara. Tipe ini menunjukkan divisi sipil kecil. Tidak semua negara memiliki tingkat administratif ini.
  • colloquial_area menunjukkan nama alternatif yang biasa digunakan untuk entity.
  • locality menunjukkan entitas politik kota atau kota yang didirikan.
  • sublocality menunjukkan entitas sipil urutan pertama di bawah lokalitas. Beberapa lokasi dapat menerima salah satu dari jenis tambahan: sublocality_level_1 ke sublocality_level_5. Setiap tingkat subdaerah adalah entitas sipil. Angka yang lebih besar menunjukkan area geografis yang lebih kecil.
  • neighborhood menunjukkan lingkungan bernama
  • premise menunjukkan lokasi yang diberi nama, biasanya bangunan atau koleksi bangunan dengan nama umum
  • subpremise menunjukkan entity urutan pertama di bawah lokasi bernama, biasanya berupa bangunan tunggal dalam kumpulan bangunan dengan nama umum
  • plus_code menunjukkan referensi lokasi yang dienkode, yang berasal dari lintang dan bujur. Plus Codes dapat digunakan sebagai pengganti alamat di tempat yang tidak ada (tempat bangunan tidak diberi nomor atau jalan tidak diberi nama). Lihat https://plus.codes untuk mengetahui detailnya.
  • postal_code menunjukkan kode pos seperti yang digunakan untuk menangani surat pos di dalam negara.
  • natural_feature menunjukkan fitur alami yang terlihat jelas.
  • airport menunjukkan bandara.
  • park menunjukkan taman bernama.
  • point_of_interest menunjukkan lokasi menarik yang disebutkan. Biasanya, "POI"ini adalah entitas lokal terkemuka yang tidak mudah masuk dalam kategori lain, seperti "Empire State Building" atau "Eiffel Tower".

Daftar jenis yang kosong menunjukkan tidak ada jenis yang diketahui untuk komponen alamat tertentu, misalnya, Lieu-dit di Prancis.

Selain yang disebutkan di atas, komponen alamat mungkin menyertakan tipe-tipe di bawah ini.

Catatan: Daftar ini bukan daftar lengkap, dan dapat berubah sewaktu-waktu.

  • floor menunjukkan lantai alamat bangunan.
  • establishment biasanya menunjukkan tempat yang belum dikategorikan.
  • landmark menunjukkan tempat terdekat yang digunakan sebagai referensi, untuk membantu navigasi.
  • point_of_interest menunjukkan lokasi menarik yang disebutkan.
  • parking menunjukkan tempat parkir atau struktur parkir.
  • post_box menunjukkan kotak pos tertentu.
  • postal_town menunjukkan pengelompokan area geografis, seperti locality dan sublocality, yang digunakan untuk alamat surat di beberapa negara.
  • room menunjukkan ruangan dengan alamat gedung.
  • street_number menunjukkan nomor jalan yang akurat.
  • bus_station, train_station, dan transit_station menunjukkan lokasi halte bus, kereta api, atau transportasi umum.

Kode Status

Kode status dapat menampilkan salah satu nilai berikut:

  • "OK" menunjukkan bahwa tidak ada error yang terjadi; alamat berhasil diuraikan dan setidaknya satu geocode ditampilkan.
  • "ZERO_RESULTS" menunjukkan bahwa geocoding berhasil tetapi tidak menampilkan hasil. Ini dapat terjadi jika geocoder meneruskan address yang tidak ada.
  • "OVER_QUERY_LIMIT" menunjukkan bahwa Anda melebihi kuota.
  • "REQUEST_DENIED" menunjukkan bahwa permintaan Anda ditolak. Halaman web tidak diizinkan untuk menggunakan geocoder.
  • "INVALID_REQUEST" secara umum menunjukkan bahwa kueri (address, components, atau latlng) tidak ada.
  • "UNKNOWN_ERROR" menunjukkan bahwa permintaan tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.
  • "ERROR" menunjukkan bahwa waktu permintaan habis atau terjadi masalah saat menghubungi server Google. Permintaan mungkin berhasil jika Anda mencoba lagi.

Dalam contoh ini, kami melakukan geocoding terhadap alamat dan menempatkan penanda pada nilai lintang dan bujur yang ditampilkan. Perhatikan bahwa pengendali diteruskan sebagai literal fungsi anonim.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Lihat contoh.

Mencondongkan Tampilan yang Terlihat

Anda dapat menginstruksikan Layanan Geocoding agar lebih memilih hasil dalam area pandang yang ditentukan (dinyatakan sebagai kotak pembatas). Anda melakukannya dengan menetapkan parameter bounds dalam literal objek GeocoderRequest untuk menentukan batas area pandang ini. Perhatikan bahwa bias hanya mengutamakan hasil dalam batas-batas tersebut; jika hasil yang lebih relevan ada di luar batas-batas ini, hasil tersebut mungkin akan disertakan.

Misalnya, geocode untuk "Winnetka" umumnya mengembalikan pinggiran kota Chicago ini:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Namun, menentukan parameter bounds yang menentukan kotak pembatas untuk Lembah San Fernando di Los Angeles akan menghasilkan geocode ini yang menampilkan lingkungan bernama "Winnetka" di lokasi tersebut:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"California",
    "short_name":"CA",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Mencondongkan Kode Region

Anda dapat menetapkan Layanan Geocoding agar menampilkan hasil yang bias ke wilayah tertentu secara eksplisit menggunakan parameter region. Parameter ini mengambil kode wilayah, yang ditetapkan sebagai subtag region Unicode dua karakter (non-numerik). Tag ini dipetakan langsung ke nilai dua karakter ccTLD ("top-level domain") seperti "quot;uk" di "co.uk" misalnya. Dalam beberapa kasus, tag region juga mendukung kode ISO-3166-1, yang terkadang berbeda dari nilai ccTLD (misalnya, "GB" untuk "Britania Raya").

Saat menggunakan parameter region:

  • Tentukan satu negara atau wilayah saja. Beberapa nilai akan diabaikan, dan dapat mengakibatkan permintaan gagal.
  • Hanya gunakan subtag region dua karakter (format Unicode CLDR). Semua input lainnya akan menghasilkan error.
  • Hanya negara dan wilayah yang tercantum dalam Detail Cakupan Google Maps Platform yang didukung.

Permintaan geocoding dapat dikirim untuk setiap domain tempat aplikasi utama Google Maps menawarkan geocoding. Perlu diperhatikan bahwa bias ini hanya memprioritaskan pemilih hasil untuk domain tertentu; jika hasil yang lebih relevan ada di luar domain tersebut, hasil tersebut mungkin akan disertakan.

Misalnya, geocode untuk "Toledo" akan menampilkan hasil ini, karena domain default untuk Layanan Geocoding disetel ke Amerika Serikat:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Geocode untuk "Toledo" dengan kolom region yang ditetapkan ke 'es' (Spanyol) akan menampilkan kota Spanyol:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Toledo",
    "short_name":"TO",
    "types":["administrative_area_level_2","political"]
  },{
    "long_name":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Pemfilteran Komponen

Anda dapat menetapkan Layanan Geocoding agar dapat menampilkan hasil alamat yang dibatasi ke area tertentu, dengan menggunakan filter komponen. Tentukan filter dalam parameter componentRestrictions. Nilai filter mendukung metode koreksi ejaan dan pencocokan parsial yang sama dengan permintaan geocoding lainnya.

Geocoder hanya menampilkan hasil yang cocok dengan semua filter komponen. Artinya, Smart Bidding mengevaluasi spesifikasi filter sebagai AND, bukan OR.

Filter komponen terdiri dari satu atau beberapa item berikut:

  • route cocok dengan nama panjang atau pendek rute.
  • locality cocok dengan jenis lokalitas dan sublokalitas.
  • administrativeArea cocok dengan semua tingkat administratif.
  • postalCode cocok dengan kode pos dan awalan kode pos.
  • country cocok dengan nama negara atau kode negara ISO 3166-1 dua huruf. Catatan: API mengikuti standar ISO untuk menentukan negara, dan pemfilteran berfungsi paling baik saat menggunakan kode ISO negara yang sesuai.

Contoh berikut menunjukkan penggunaan parameter componentRestrictions untuk memfilter menurut country dan postalCode:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Geocoding Terbalik (Pencarian Alamat)

Istilah geocoding umumnya mengacu pada penerjemahan alamat yang dapat dibaca manusia menjadi lokasi pada peta. Proses menerjemahkan lokasi pada peta menjadi alamat yang dapat dibaca manusia, dikenal sebagai geocoding terbalik.

Daripada menyediakan address tekstual, berikan pasangan garis lintang/bujur yang dipisahkan koma dalam parameter location.

Contoh berikut meng-geocoding nilai lintang/bujur dan memusatkan peta di lokasi tersebut, yang menampilkan jendela info dengan alamat berformat:

TypeScript

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
Lihat contoh

Coba Sampel

Perhatikan bahwa dalam contoh sebelumnya, kami menampilkan hasil pertama dengan memilih results[0]. Geocoder terbalik sering menampilkan lebih dari satu hasil. Alamat yang di-geocoding bukan hanya alamat pos, tetapi cara apa pun untuk memberi nama lokasi secara geografis. Misalnya, saat geocoding titik di kota Chicago, titik yang di-geocoding dapat diberi label sebagai alamat jalan, sebagai kota (Chicago), sebagai negara bagian (Illinois) atau sebagai negara (Amerika Serikat ). Semua adalah alamat untuk geocoder tersebut. Geocoder terbalik akan menampilkan semua hasil ini.

Geocoder terbalik akan mencocokkan entitas politik (negara, provinsi, kota dan lingkungan), alamat jalan, dan kode pos.

Berikut adalah contoh daftar alamat yang mungkin ditampilkan oleh kueri di atas:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Alamat akan dikembalikan dengan urutan dari yang paling cocok hingga yang paling tidak cocok. Biasanya, alamat yang lebih tepat adalah hasil yang paling menonjol, seperti dalam kasus ini. Perhatikan bahwa kami menampilkan berbagai jenis alamat, mulai dari alamat yang paling spesifik hingga entitas politik yang kurang spesifik seperti lingkungan, kota, wilayah, negara bagian, dll. Jika ingin mencocokkan alamat yang lebih umum, Anda dapat memeriksa kolom results[].types.

Catatan: Geocoding terbalik bukanlah ilmu pasti. Geocoder akan mencoba menemukan lokasi alamat terdekat dalam toleransi tertentu.

Mengambil Alamat untuk ID Tempat

Berikan placeId untuk menemukan alamat untuk ID tempat tertentu. ID tempat adalah ID unik yang dapat digunakan dengan Google API lainnya. Misalnya, Anda dapat menyediakan placeId yang ditampilkan oleh Roads API untuk mendapatkan alamat titik yang diikat. Untuk informasi selengkapnya tentang ID tempat, lihat ringkasan ID tempat.

Jika Anda menyediakan placeId, permintaan tidak boleh berisi salah satu kolom berikut:

  • address
  • latLng
  • location
  • componentRestrictions

Contoh berikut menerima ID tempat, menemukan alamat yang sesuai, dan memusatkan peta di lokasi tersebut. Tindakan ini juga akan menampilkan jendela info yang menampilkan alamat berformat dari tempat yang relevan:

TypeScript

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;

JavaScript

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
Lihat contoh

Coba Sampel