Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Maps JavaScript API

Untuk membantu Anda memulai, kami akan memandu Anda melalui Google Developers Console untuk melakukan beberapa hal terlebih dahulu:

  1. Buat atau pilih sebuah proyek
  2. Aktifkan Google Maps JavaScript API dan layanan terkait
  3. Buat kunci yang sesuai
Lanjutkan

Places Library

Ringkasan

Berbagai fungsi di Google Places JavaScript Library memungkinkan aplikasi Anda menelusuri tempat (didefinisikan dalam API ini sebagai tempat usaha, lokasi geografis, atau tempat menarik yang menonjol) yang terdapat dalam area ditentukan, seperti batas-batas peta, atau di sekitar titik tetap.

Google Places API menawarkan fitur pelengkapan otomatis yang bisa Anda gunakan untuk memberikan aplikasi Anda perilaku prediksi-penelusuran pada bidang penelusuran Google Maps. Bila pengguna mulai mengetik alamat, pelengkapan otomatis akan mengisikan sisanya. Untuk informasi selengkapnya, lihat dokumentasi autocomplete.

Memulai

Sebelum menggunakan pustaka Places di Google Maps JavaScript API, terlebih dahulu pastikan Google Places API Web Service telah diaktifkan di Google API Console, dalam proyek yang sama dengan yang Anda persiapkan untuk Google Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

  1. Masuklah ke Google API Console.
  2. Klik tombol Select a project, kemudian pilih proyek yang sama dengan yang Anda persiapkan untuk Google Maps JavaScript API dan klik Open.
  3. Dari daftar API di Dashboard, cari Google Places API Web Service.
  4. Jika sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak dicantumkan, aktifkan:
    1. Di bagian atas laman, pilih ENABLE API untuk menampilkan tab Library. Atau, dari menu sisi kiri, pilih Library.
    2. Telusuri Google Places API Web Service, kemudian pilih dari daftar hasil.
    3. Pilih ENABLE. Bila proses selesai, Google Places API Web Service akan muncul dalam daftar API di Dashboard.

Memuat Pustaka

Layanan Places adalah pustaka mandiri, terpisah dari kode utama Maps JavaScript API. Untuk menggunakan fungsionalitas yang ada dalam pustaka ini, terlebih dahulu Anda harus memuatnya menggunakan parameter libraries di URL bootstrap Maps API:

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

Lihat Ringkasan Pustaka untuk informasi selengkapnya.

Kebijakan dan batas penggunaan

Kuota

Google Places API Web Service dan Place Autocomplete berbagi kuota penggunaan seperti dijelaskan dalam dokumentasi Batas Penggunaan untuk Google Places API Web Service. Batas penggunaan ini juga berlaku saat menggunakan Places Library in the Google Maps JavaScript API. Penggunaan harian dihitung sebagai gabungan jumlah permintaan sisi-klien dan sisi-server.

Kebijakan

Penggunaan layanan Places Library in the Google Maps JavaScript API harus sesuai dengan kebijakan yang dijelaskan untuk Google Places API Web Service.

Place Search

Dengan layanan Places Anda bisa melakukan empat jenis penelusuran:

  • Nearby Search mengembalikan daftar tempat terdekat berdasarkan lokasi pengguna.
  • Text Search mengembalikan daftar tempat terdekat berdasarkan string penelusuran, misalnya "Pizza".
  • Radar Search mengembalikan daftar besar berisi banyak tempat dalam radius penelusuran yang ditetapkan, namun kurang detail dibandingkan Nearby Search atau Text Search.
  • Permintaan Place Details mengembalikan informasi lebih detail tentang tempat tertentu, termasuk ulasan pengguna.

Informasi yang dikembalikan bisa berisi tempat usaha - seperti restoran, toko, dan kantor — serta hasil 'geocode', yang menunjukkan alamat, area politik seperti kota kecil dan kota besar, serta tempat menarik lainnya.

Permintaan Nearby Search

Nearby Search memungkinkan Anda menelusuri tempat dalam area yang ditetapkan dengan kata kunci atau ketikan. Nearby Search harus selalu menyertakan lokasi, yang bisa ditetapkan dalam salah satu dari dua cara:

  • LatLngBounds.
  • area melingkar didefinisikan sebagai kombinasi dari properti location — yang menetapkan pusat lingkaran sebagai objek LatLng — dan radius, yang diukur dalam meter.

Penelusuran Places Nearby dijalankan dengan panggilan ke metode nearbySearch() dari PlacesService, yang akan mengembalikan larik objek PlaceResult. Perhatikan, metode nearbySearch() menggantikan metode search() mulai versi 3.9.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

Metode ini mengambil permintaan dengan bidang-bidang berikut:

  • Salah satu dari:
    • bounds, harus berupa objek google.maps.LatLngBounds yang mendefinisikan area penelusuran persegi panjang; atau
    • location dan radius; yang pertama mengambil objek google.maps.LatLng, dan yang kedua mengambil integer sederhana, yang menyatakan radius lingkaran dalam meter. Radius maksimum yang diperbolehkan adalah 50.000 meter. Perhatikan bahwa saat rankBy disetel ke DISTANCE, Anda harus menetapkan sebuah location tetapi Anda tidak bisa menetapkan radius atau bounds.
  • keyword (opsional) — Istilah yang akan dicocokkan dengan semua bidang yang tersedia, termasuk namun tidak terbatas pada nama, tipe, dan alamat, serta ulasan pelanggan dan materi pihak ketiga lainnya.
  • minprice dan maxprice (opsional) — Membatasi hasil hanya pada tempat-tempat yang berada dalam jangkauan yang ditetapkan. Nilai yang valid berkisar antara 0 (paling terjangkau) hingga 4 (paling mahal), inklusif.
  • name (opsional) — Istilah yang akan dicocokkan dengan nama-nama tempat. Hasil akan dibatasi pada nilai nama yang diteruskan. Perhatikan, sebuah tempat bisa memiliki nama tambahan yang dikaitkan dengannya, selain nama yang tercantum. API akan mencoba untuk mencocokkan nilai name yang diteruskan terhadap semua nama-nama ini; akibatnya, tempat mungkin dikembalikan dalam hasil yang mencantumkan nama yang tidak cocok dengan istilah penelusuran, namun cocok dengan nama yang dikaitkan.
  • openNow (opsional) — Sebuah nilai boolean, yang menunjukkan layanan Places hanya mengembalikan tempat yang sedang buka pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan dikembalikan jika Anda menyertakan parameter ini dalam kueri. Menyetel openNow ke false tidak berpengaruh.
  • rankby (opsional) — Menetapkan urutan pencantuman hasil. Kemungkinan nilainya:
    • google.maps.places.RankBy.PROMINENCE (default). Opsi ini menyortir hasil menurut seberapa pentingnya. Ranking akan mengutamakan tempat yang menonjol dalam radius yang disetel dibandingkan tempat terdekat yang cocok namun kurang menonjol. Tempat yang menonjol bisa dipengaruhi oleh peringkat suatu tempat dalam indeks Google, popularitas global, dan faktor lainnya. Bila google.maps.places.RankBy.PROMINENCE telah ditetapkan, maka diperlukan parameter radius.
    • google.maps.places.RankBy.DISTANCE. Opsi ini akan menyortir hasil dalam urutan menaik berdasarkan jaraknya dari location (diperlukan) yang ditetapkan. Perhatikan bahwa Anda tidak bisa menetapkan bounds dan/atau radius khusus jika Anda menetapkan RankBy.DISTANCE. Jika Anda menetapkan RankBy.DISTANCE, satu atau beberapa keyword, name, atau type diperlukan.
  • type — Membatasi hasil penelusuran ke tempat yang cocok dengan tipe yang ditetapkan. Hanya satu tipe yang boleh ditetapkan (jika lebih dari satu tipe disediakan, semua tipe setelah entri pertama akan diabaikan). Lihat daftar tipe yang didukung.
  • types (tidak digunakan lagi) — Sebuah larik yang berisi satu atau beberapa tipe yang didukung. Layanan akan mengembalikan serangkaian hasil terbaik untuk serangkaian tipe yang diberikan.

Anda juga harus meneruskan metode callback ke nearbySearch(), untuk menangani objek hasil dan respons google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    types: ['store']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Tampilkan contoh (place-search.html)

Permintaan Text Search

Layanan Google Places Text Search adalah layanan web yang mengembalikan informasi tentang satu set tempat berdasarkan suatu string - misalnya "pizza in New York" atau "shoe stores near Ottawa". Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan kecondongan lokasi yang telah disetel. Respons penelusuran akan menyertakan daftar tempat. Anda bisa mengirim permintaan Place Details untuk informasi selengkapnya tentang tempat dalam respons.

Text Searches dijalankan dengan panggilan ke metode textSearch() dari PlacesService. 

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

Metode ini mengambil permintaan dengan bidang-bidang berikut:

  • query (diperlukan) String teks yang digunakan untuk menelusuri, misalnya: "restaurant". Layanan Places akan mengembalikan bakal hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat. Parameter ini menjadi opsional jika parameter type juga digunakan dalam permintaan penelusuran.
  • Opsional:
    • openNow — Sebuah nilai boolean, yang menunjukkan layanan Places hanya mengembalikan tempat yang sedang buka pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan dikembalikan jika Anda menyertakan parameter ini dalam kueri. Menyetel openNow ke false tidak berpengaruh.
    • minprice dan maxprice — Membatasi hasil agar hanya menampilkan tempat dengan tingkat harga yang ditetapkan. Nilai yang valid berkisar dari 0 (paling terjangkau) hingga 4 (paling mahal), inklusif.
    • Salah satu dari:
      • bounds — Objek google.maps.LatLngBounds yang mendefinisikan bidang persegi panjang tempat menelusuri; atau
      • location dan radius — Anda bisa mencondongkan hasil ke lingkaran yang ditetapkan dengan meneruskan parameter location dan radius. Ini akan menginstruksikan layanan Places agar lebih memilih menampilkan hasil dalam lingkaran itu. Hasil di luar area yang didefinisikan mungkin tetap ditampilkan. Lokasi akan mengambil objek google.maps.LatLng, dan radius mengambil integer sederhana, yang menyatakan radius lingkaran dalam meter. Radius maksimum yang diperbolehkan adalah 50.000 meter.
    • type — Membatasi hasil penelusuran ke tempat yang cocok dengan tipe yang ditetapkan. Hanya satu tipe yang boleh ditetapkan (jika lebih dari satu tipe disediakan, semua tipe setelah entri pertama akan diabaikan). Lihat daftar tipe yang didukung.
    • types (tidak digunakan lagi) — Sebuah larik yang berisi satu atau beberapa tipe yang didukung. Layanan ini akan mengembalikan hasil yang cocok dengan salah satu tipe yang ditetapkan.

Anda juga harus meneruskan metode callback ke textSearch(), untuk menangani objek hasil dan respons google.maps.places.PlacesServiceStatus.

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

  map = new google.maps.Map(document.getElementById('map'), {
      center: pyrmont,
      zoom: 15
    });

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Permintaan Radar Search

Radar Search memungkinkan Anda menelusuri tempat dalam radius penelusuran yang ditetapkan dengan kata kunci, ketikan, atau nama. Radar Search mengembalikan hasil lebih banyak daripada Nearby Search atau Text Search, namun berisi bidang yang lebih sedikit. Anda bisa memanggil PlacesService.getDetails() untuk mendapatkan informasi selengkapnya tentang salah satu tempat dalam respons.

Objek PlaceResult yang dikembalikan oleh radarSearch() hanya berisi properti berikut:

  • geometry.location
  • place_id
  • reference (Catatan: reference tidak digunakan lagi karena sudah ada place_id, seperti dijelaskan dalam pemberitahuan penghentian pada laman ini.)

Places Radar Search dijalankan dengan panggilan ke metode radarSearch() dari PlacesService, yang akan mengembalikan larik hingga 200 objek PlaceResult.

service = new google.maps.places.PlacesService(map);
service.radarSearch(request, callback);

Metode ini mengambil permintaan dengan bidang-bidang berikut:

  • Salah satu dari:
    • bounds, harus berupa objek google.maps.LatLngBounds yang mendefinisikan area penelusuran persegi panjang; atau
    • location dan radius; yang pertama mengambil objek google.maps.LatLng, dan yang kedua mengambil integer sederhana, yang menyatakan radius lingkaran dalam meter. Radius maksimum yang diperbolehkan adalah 50.000 meter.
  • Setidaknya salah satu dari:
    • keyword (opsional) — Istilah yang akan dicocokkan dengan semua bidang yang tersedia, termasuk namun tidak terbatas pada nama, tipe, dan alamat, serta ulasan pelanggan dan materi pihak ketiga lainnya.
    • name (opsional) — Istilah yang akan dicocokkan dengan nama-nama tempat. Hasil akan dibatasi pada nilai nama yang diteruskan. Perhatikan, sebuah tempat bisa memiliki nama tambahan yang dikaitkan dengannya, selain nama yang tercantum. API akan mencoba untuk mencocokkan nilai name yang diteruskan terhadap semua nama-nama ini; akibatnya, tempat mungkin dikembalikan dalam hasil yang mencantumkan nama yang tidak cocok dengan istilah penelusuran, namun cocok dengan nama yang dikaitkan.
    • type — Membatasi hasil penelusuran ke tempat yang cocok dengan tipe yang ditetapkan. Hanya satu tipe yang boleh ditetapkan (jika lebih dari satu tipe disediakan, semua tipe setelah entri pertama akan diabaikan). Lihat daftar tipe yang didukung.
    • types (tidak digunakan lagi) — Sebuah larik yang berisi satu atau beberapa tipe yang didukung. Layanan akan mengembalikan serangkaian hasil terbaik untuk serangkaian tipe yang diberikan.
  • Opsional:
    • minPriceLevel dan maxPriceLevel (opsional) — Membatasi hasil hanya pada tempat yang berada dalam tingkat harga yang ditetapkan. Nilai yang valid berkisar dari 0 (paling terjangkau) hingga 4 (paling mahal), inklusif.
    • openNow — Sebuah nilai boolean, yang menunjukkan layanan Places hanya mengembalikan tempat yang sedang buka pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan dikembalikan jika Anda menyertakan parameter ini dalam kueri. Menyetel openNow ke false tidak berpengaruh.

Anda juga harus meneruskan metode callback ke radarSearch(), untuk menangani objek PlaceResults dan google.maps.places.PlacesServiceStatus.

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

  infoWindow = new google.maps.InfoWindow();
  service = new google.maps.places.PlacesService(map);

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'https://developers.google.com/maps/documentation/javascript/images/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}
<div id="map"></div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap&libraries=places,visualization" async defer></script>

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

  infoWindow = new google.maps.InfoWindow();
  service = new google.maps.places.PlacesService(map);

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'https://developers.google.com/maps/documentation/javascript/images/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}

Tampilkan contoh (place-radar-search.html).

Respons Penelusuran

Kode Status

Objek respons PlacesServiceStatus berisi status permintaan, dan mungkin berisi informasi debug untuk membantu Anda melacak penyebab gagalnya permintaan. Nilai status yang mungkin adalah:

  • ERROR: Ada masalah saat menghubungi server Google.
  • INVALID_REQUEST: Permintaan ini tidak valid.
  • OK: Respons berisi hasil yang valid.
  • OVER_QUERY_LIMIT: Laman web telah melampaui kuota permintaannya.
  • REQUEST_DENIED: Laman web tidak diperbolehkan menggunakan PlacesService.
  • UNKNOWN_ERROR: Permintaan PlacesService tidak bisa diproses karena kesalahan server. Permintaan mungkin berhasil jika Anda mencoba lagi.
  • ZERO_RESULTS: Tidak ada hasil yang ditemukan untuk permintaan ini.

Hasil Place Search

Fungsi nearbySearch() dan textSearch() mengembalikan larik objek PlaceResult. Fungsi radarSearch() mengembalikan subset bidang dalam PlaceResult, seperti dijelaskan di atas.

Setiap objek PlaceResult mungkin menyertakan properti berikut:

  • formatted_address adalah string berisi alamat yang bisa dibaca orang untuk tempat ini. Sering kali alamat ini sama dengan "alamat pos". Properti formatted_address hanya dikembalikan untuk Text Search.
  • geometry: Informasi yang terkait dengan geometri tempat. Ini berisi:
    • location memberikan garis lintang dan garis bujur suatu tempat.
    • viewport mendefinisikan viewport yang disukai pada peta saat menampilkan tempat ini.
  • html_attributions: Larik atribusi yang harus Anda tampilkan saat menampilkan hasil penelusuran. Setiap entri dalam larik berisi teks HTML untuk atribusi tunggal. Catatan: Ini adalah kumpulan semua atribusi untuk seluruh respons penelusuran. Semua objek PlaceResult dalam respons, karenanya berisi daftar atribusi yang identik.
  • icon: URL ke sumber daya gambar yang bisa digunakan untuk merepresentasikan tipe tempat ini.
  • id: berisi sebuah identifier unik yang menunjukkan tempat ini. Identifier ini tidak boleh digunakan untuk mengambil informasi tentang tempat ini, namun bisa digunakan untuk mengkonsolidasikan data tentang tempat ini, dan untuk memverifikasi identitas tempat di semua penelusuran terpisah. Karena ID kadang-kadang bisa berubah, disarankan agar ID tempat yang tersimpan dibandingkan dengan ID yang dikembalikan dalam permintaan Details selanjutnya untuk tempat yang sama, dan diperbarui jika diperlukan. Catatan: id tidak digunakan lagi karena sudah ada place_id, seperti dijelaskan dalam pemberitahuan penghentian pada laman ini.
  • name: Nama tempat.
  • opening_hours bisa berisi informasi berikut:
    • open_now adalah nilai boolean yang menunjukkan apakah tempat itu buka pada waktu saat ini.
  • place_id sebuah identifier tekstual yang secara unik mengidentifikasi tempat. Untuk mengambil informasi tentang tempat, teruskan identifier ini dalam bidang placeId pada permintaan Place Details. Ketahui selengkapnya tentang cara mereferensikan sebuah tempat dengan ID tempat.
  • rating berisi peringkat tempat ini, dari 0,0 hingga 5,0, berdasarkan gabungan ulasan pengguna.
  • reference berisi token yang bisa digunakan untuk kueri layanan Details di masa mendatang. Token ini mungkin berbeda dari referensi yang digunakan dalam permintaan ke layanan Details. Disarankan agar referensi tempat yang tersimpan diperbarui secara rutin. Meskipun token ini secara unik mengidentifikasi tempat, hal yang sebaliknya tidak berlaku: suatu tempat bisa memiliki banyak token referensi yang valid. Catatan: reference tidak digunakan lagi karena sudah ada place_id, seperti dijelaskan dalam pemberitahuan penghentian pada laman ini.
  • types Sebuah larik tipe untuk tempat ini (misalnya, ["political", "locality"] atau ["restaurant", "lodging"]).
  • vicinity: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor rumah, dan lokalitas, namun bukan provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilai vicinity 5/48 Pirrama Road, Pyrmont.

Mengakses Hasil Tambahan

Secara default, setiap penelusuran tempat mengembalikan hingga 20 hasil per kueri. Akan tetapi, setiap penelusuran bisa mengembalikan hingga 60 hasil, yang terbagi dalam tiga laman. Laman tambahan tersedia melalui objek PlaceSearchPagination. Untuk mengakses laman tambahan Anda harus menangkap objek PlaceSearchPagination melalui fungsi callback. Objek PlaceSearchPagination didefinisikan sebagai:

  • hasNextPage properti boolean yang menunjukkan apakah tersedia hasil lebih lanjut. true bila ada laman hasil tambahan.
  • nextPage() fungsi yang akan mengembalikan set hasil berikutnya. Setelah menjalankan penelusuran, Anda harus menunggu dua detik sebelum laman hasil berikutnya akan tersedia.

Untuk melihat set hasil berikutnya, panggil nextPage. Setiap laman hasil harus ditampilkan sebelum menampilkan laman hasil berikutnya. Perhatikan, setiap penelusuran dihitung sebagai satu permintaan terhadap batas penggunaan Anda.

Contoh di bawah memperagakan cara mengubah fungsi callback Anda untuk menangkap objek PlaceSearchPagination, sehingga Anda bisa mengeluarkan beberapa permintaan penelusuran.

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

  map = new google.maps.Map(document.getElementById('map'), {
    center: pyrmont,
    zoom: 17
  });

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    type: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var image = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25)
    };

    var marker = new google.maps.Marker({
      map: map,
      icon: image,
      title: place.name,
      position: place.geometry.location
    });

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}
<div id="map"></div>
<div id="right-panel">
  <h2>Results</h2>
  <ul id="places"></ul>
  <button id="more">More results</button>
</div>
/* Always set the map height explicitly to define the size of the div
 * element that contains the map. */
#map {
  height: 100%;
}
/* Optional: Makes the sample page fill the window. */
html, body {
  height: 100%;
  margin: 0;
  padding: 0;
}
#right-panel {
  font-family: 'Roboto','sans-serif';
  line-height: 30px;
  padding-left: 10px;
}

#right-panel select, #right-panel input {
  font-size: 15px;
}

#right-panel select {
  width: 100%;
}

#right-panel i {
  font-size: 12px;
}
#right-panel {
  font-family: Arial, Helvetica, sans-serif;
  position: absolute;
  right: 5px;
  top: 60%;
  margin-top: -195px;
  height: 330px;
  width: 200px;
  padding: 5px;
  z-index: 5;
  border: 1px solid #999;
  background: #fff;
}
h2 {
  font-size: 22px;
  margin: 0 0 5px 0;
}
ul {
  list-style-type: none;
  padding: 0;
  margin: 0;
  height: 271px;
  width: 200px;
  overflow-y: scroll;
}
li {
  background-color: #f1f1f1;
  padding: 10px;
  text-overflow: ellipsis;
  white-space: nowrap;
  overflow: hidden;
}
li:nth-child(odd) {
  background-color: #fcfcfc;
}
#more {
  width: 100%;
  margin: 5px 0 0 0;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&libraries=places&callback=initMap" async defer></script>

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

  map = new google.maps.Map(document.getElementById('map'), {
    center: pyrmont,
    zoom: 17
  });

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    type: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var image = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25)
    };

    var marker = new google.maps.Marker({
      map: map,
      icon: image,
      title: place.name,
      position: place.geometry.location
    });

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}

Tampilkan contoh (place-search-pagination.html).

Place Details

Selain menyediakan daftar tempat dalam suatu area, layanan Places juga mengembalikan informasi detail tentang tempat tertentu. Setelah tempat dikembalikan dalam respons penelusuran tempat, place ID bisa digunakan untuk meminta detail tambahan tentang tempat itu, seperti alamat lengkap, nomor telepon, peringkat pengguna dan ulasan, dll. (referensi tempat juga bisa digunakan untuk mendapatkan detail tempat, namun bidang ini tidak digunakan lagi karena sudah ada ID tempat, seperti dijelaskan dalam pemberitahuan penghentian pada laman ini.)

Permintaan Place Details

Place Details diminta dengan panggilan ke metode getDetails() layanan.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

Metode ini mengambil permintaan, berisi placeId atau reference tempat yang diinginkan. reference tidak digunakan lagi karena sudah ada placeId, seperti dijelaskan dalam pemberitahuan penghentian pada laman ini. Ketahui selengkapnya tentang cara mereferensikan sebuah tempat dengan ID tempat.

Ini juga membutuhkan metode callback, yang perlu menangani kode status yang diteruskan dalam respons google.maps.places.PlacesServiceStatus, serta objek google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4'
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

Tampilkan contoh (place-details.html)

Respons Place Details

Kode Status

Objek respons PlacesServiceStatus berisi status permintaan, dan mungkin berisi informasi debug untuk membantu Anda melacak penyebab gagalnya permintaan Place Details. Nilai status yang mungkin adalah:

  • ERROR: Ada masalah saat menghubungi server Google.
  • INVALID_REQUEST: Permintaan ini tidak valid.
  • OK: Respons berisi hasil yang valid.
  • OVER_QUERY_LIMIT: Laman web telah melampaui kuota permintaannya.
  • NOT_FOUND lokasi yang disebutkan tidak ditemukan dalam database Places.
  • REQUEST_DENIED: Laman web tidak diperbolehkan menggunakan PlacesService.
  • UNKNOWN_ERROR: Permintaan PlacesService tidak bisa diproses karena kesalahan server. Permintaan mungkin berhasil jika Anda mencoba lagi.
  • ZERO_RESULTS: Tidak ada hasil yang ditemukan untuk permintaan ini.

Hasil Place Details

Panggilan getDetails() yang berhasil akan mengembalikan objek PlaceResult bersama properti berikut:

  • address_components: Kumpulan komponen alamat untuk lokasi tempat ini. Lihat bagian Tipe Komponen Alamat layanan Geocoding untuk detail selengkapnya.
  • formatted_address: Alamat lengkap tempat tersebut.
  • formatted_phone_number: Nomor telepon tempat, diformat sesuai dengan konvensi penomoran di daerah tersebut.
  • geometry: Informasi yang terkait dengan geometri tempat. Ini berisi:
    • location memberikan garis lintang dan garis bujur suatu tempat.
    • viewport mendefinisikan viewport yang disukai pada peta saat menampilkan tempat ini.
  • html_attributions: Teks atribusi yang akan ditampilkan untuk hasil tempat ini.
  • icon: URL ke sumber daya gambar yang bisa digunakan untuk merepresentasikan tipe tempat ini.
  • id: berisi sebuah identifier unik yang menunjukkan tempat ini. Identifier ini tidak boleh digunakan untuk mengambil informasi tentang tempat ini, namun bisa digunakan untuk mengkonsolidasikan data tentang tempat ini, dan untuk memverifikasi identitas tempat di semua penelusuran terpisah. Karena ID kadang-kadang bisa berubah, disarankan agar ID tempat yang tersimpan dibandingkan dengan ID yang dikembalikan dalam permintaan Details selanjutnya untuk tempat yang sama, dan diperbarui jika diperlukan. Catatan: id tidak digunakan lagi karena sudah ada place_id, seperti dijelaskan dalam pemberitahuan penghentian pada laman ini.
  • international_phone_number berisi nomor telepon tempat tersebut dalam format internasional. Format internasional menyertakan kode negara dan diawali dengan tanda tambah (+). Misalnya, international_phone_number untuk kantor Google di Sydney, Australia adalah +61 2 9374 4000.
  • name: Nama tempat.
  • utc_offset berisi offset jumlah menit antara zona waktu tempat ini sekarang dari UTC. Misalnya, untuk tempat di Sydney, Australia saat terjadi penyesuaian waktu di musim panas akan menjadi 660 (+11 jam dari UTC), dan untuk tempat di California di luar penyesuaian waktu di musim panas akan menjadi -480 menit (-8 jam dari UTC).
  • opening_hours berisi informasi berikut:
    • open_now adalah nilai boolean yang menunjukkan apakah tempat itu buka pada waktu saat ini.
    • periods[] adalah larik jangka waktu buka yang mencakup tujuh hari, mulai dari hari Minggu, dalam urutan kronologis. Setiap jangka waktu berisi:
      • open berisi sepasang objek hari dan waktu yang menjelaskan kapan tempat tersebut buka:
        • day angka 0–6, yang menyatakan hari-hari dalam seminggu, mulai hari Minggu. Misalnya, 2 berarti Selasa.
        • time bisa berisi waktu dalam sehari dalam format 24 jam hhmm (nilainya berkisar 0000–2359). time akan dilaporkan dalam zona waktu tempat tersebut.
      • close berisi pasangan objek hari dan waktu yang menjelaskan kapan tempat tersebut tutup. Catatan: Jika sebuah tempat selalu buka, bagian close akan menghilang dari respons. Aplikasi bisa berpatokan pada kondisi selalu-buka yang dinyatakan berupa jangka waktu open yang berisi day dengan nilai 0 dan time dengan nilai 0000, dan tidak ada close.
    • weekday_text adalah larik berisi tujuh string yang menyatakan jam buka yang telah diformat untuk setiap hari dalam seminggu. Jika parameter language telah ditetapkan dalam permintaan Place Details, Places Service akan memformat dan melokalkan jam buka sesuai dengan bahasa itu. Urutan elemen dalam larik ini bergantung pada parameter language. Beberapa bahasa memulai pekan pada hari Senin sementara yang lain mulai pada hari Minggu.
  • permanently_closed: flag boolean yang menunjukkan apakah tempat tersebut tutup untuk selamanya (bernilai true). Jika tempat tersebut tidak tutup selamanya, flag tidak ada dalam respons.
  • photos[]: larik objek PlacePhoto. Sebuah PlacePhoto bisa digunakan untuk memperoleh foto bersama metode getUrl(), atau Anda bisa memeriksa objek untuk mengetahui nilai berikut:
    • height: tinggi maksimum gambar, dalam piksel.
    • width: lebar maksimum gambar, dalam piksel.
    • html_attributions: Teks atribusi yang akan ditampilkan bersama foto tempat ini.
  • place_id: Sebuah identifier tekstual yang secara unik mengidentifikasi tempat dan bisa digunakan untuk mengambil informasi tentang tempat melalui permintaan Place Details. Ketahui selengkapnya tentang cara mereferensikan sebuah tempat dengan ID tempat.
  • rating: Peringkat tempat ini, dari 0,0 hingga 5,0, berdasarkan gabungan ulasan pengguna.
  • reference berisi token yang bisa digunakan untuk kueri layanan Details di masa mendatang. Token ini mungkin berbeda dari referensi yang digunakan dalam permintaan ke layanan Details. Disarankan agar referensi tempat yang tersimpan diperbarui secara rutin. Meskipun token ini secara unik mengidentifikasi tempat, hal yang sebaliknya tidak berlaku: suatu tempat bisa memiliki banyak token referensi yang valid. Catatan: reference tidak digunakan lagi karena sudah ada place_id, seperti dijelaskan dalam pemberitahuan penghentian pada laman ini.
  • reviews larik yang berisi hingga lima ulasan. Setiap ulasan terdiri dari beberapa komponen:
    • aspects[] berisi larik objek PlaceAspectRating, masing-masing memberikan peringkat atribut tunggal untuk tempat usaha tersebut. Objek pertama dalam larik dianggap sebagai aspek utama. Setiap PlaceAspectRating didefinisikan sebagai:
      • type nama aspek yang akan diberi peringkat. Tipe-tipe berikut ini didukung: appeal, atmosphere, decor, facilities, food, overall, quality dan service.
      • rating peringkat pengguna untuk aspek tertentu, dari 0 hingga 3.
    • author_name nama pengguna yang menyerahkan ulasan. Ulasan anonim diatribusikan dengan "Pengguna Google". Jika parameter bahasa telah disetel, maka kalimat "Pengguna Google" akan mengembalikan string lokal.
    • author_url URL ke profil pengguna Google+, jika tersedia.
    • language kode bahasa IETF yang menunjukkan bahasa yang digunakan dalam ulasan pengguna. Bidang ini berisi tag bahasa utama saja, dan bukan tag sekunder yang menunjukkan negara atau region. Misalnya, semua ulasan dalam bahasa Inggris akan diberi tag 'en', dan bukan 'en-AU' atau 'en-UK' dan seterusnya.
    • rating peringkat keseluruhan pengguna untuk tempat ini. Ini adalah bilangan bulat, berkisar dari 1 hingga 5.
    • text ulasan pengguna. Saat mengulas sebuah lokasi dengan Google Places, ulasan teks dianggap opsional; karena itu, bidang ini mungkin kosong.
  • types Sebuah larik tipe untuk tempat ini (misalnya, ["political", "locality"] atau ["restaurant", "lodging"]).
  • url: URL laman resmi Google untuk tempat ini. Ini adalah laman milik Google berisi informasi terbaik yang tersedia tentang tempat ini. Aplikasi harus menautkan ke atau menyematkan laman ini pada setiap layar yang menampilkan hasil detail tentang tempat itu kepada pengguna.
  • vicinity: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor rumah, dan lokalitas, namun bukan provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilai vicinity 5/48 Pirrama Road, Pyrmont. Properti vicinity hanya dikembalikan untuk Nearby Search.
  • website mencantumkan situs web resmi untuk tempat ini, seperti laman beranda bisnis.

Peringkat multidimensi mungkin tidak tersedia untuk semua lokasi. Jika ulasan terlalu sedikit maka detail respons akan menyertakan peringkat lawas dengan skala 0,0 hingga 5,0 (jika tersedia) atau tidak ada peringkat sama sekali.

Mereferensikan sebuah Tempat dengan ID Tempat

Tempat di peta Google bisa secara unik direferensikan dengan ID tempatnya. ID tempat tersedia untuk sebagian besar lokasi, termasuk lokasi bisnis, landmark, taman, dan persimpangan. Semua ID ini stabil, maksudnya, sekali Anda mengidentifikasi ID tempat untuk lokasi tersebut, Anda bisa menggunakan kembali nilainya bila suatu saat ingin mencari lokasi itu lagi.

Untuk menggunakan ID tempat dalam aplikasi, terlebih dahulu Anda harus menemukan ID, yang tersedia di PlaceResult dari Place Search atau permintaan Details. Selanjutnya Anda bisa menggunakan ID tempat ini untuk mencari Place Details, atau mengaktifkan Save Attribution di peta yang dimasuki.

ID tempat dikecualikan dari pembatasan caching yang disebutkan di Bagian 10.5.d di Ketentuan Layanan Google Maps API. Karena itu Anda bisa menyimpan nilai ID tempat secara tak terbatas. 

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

Place Photos

Fitur Place Photo memungkinkan Anda menambahkan materi fotografi berkualitas tinggi ke situs Anda. Layanan Photo memberi Anda akses ke jutaan foto yang tersimpan dalam database Places dan Google+ Local. Bila Anda mengambil informasi tempat menggunakan permintaan Place Details, referensi foto akan dikembalikan untuk materi fotografi yang relevan. Permintaan Nearby Search dan Text Search juga akan mengembalikan referensi foto tunggal per tempat, bila relevan. Dengan layanan Photo, Anda kemudian bisa mengakses foto yang direferensikan dan mengubah ukuran gambar ke ukuran yang optimal untuk aplikasi Anda.

Larik objek PlacePhoto akan dikembalikan sebagai bagian dari PlaceResult untuk setiap permintaan getDetails(), textSearch() atau nearbySearch() yang dibuat terhadap PlacesService.

Catatan: Jumlah foto yang dikembalikan akan bervariasi menurut permintaan.

  • Nearby Search atau Text Search akan mengembalikan paling banyak satu objek PlacePhoto.
  • Radar Search tidak mengembalikan informasi foto.
  • Permintaan Details akan mengembalikan hingga sepuluh objek PlacePhoto.

Anda bisa meminta URL untuk gambar terkait dengan memanggil metode PlacePhoto.getUrl(), dan meneruskan objek PhotoOptions yang valid. Objek PhotoOptions memungkinkan Anda menetapkan tinggi dan lebar maksimum gambar yang diinginkan. Jika Anda menetapkan nilai untuk kedua max_height dan max_width, layanan foto akan mengubah ukuran gambar menurut ukuran yang lebih kecil, dengan tetap menjaga rasio aspek asal.

Cuplikan kode berikut menerima objek tempat, dan menambahkan marker ke peta jika terdapat foto. Gambar marker default digantikan dengan versi kecil dari foto.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({'maxWidth': 35, 'maxHeight': 35})
  });
}

Kirim masukan tentang...

Laman ini
Masukan dokumentasi
Google Maps JavaScript API
Google Maps JavaScript API
Masukan produk
Butuh bantuan? Kunjungi laman dukungan kami.