Places Library

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.
Pilih platform: Android iOS JavaScript Layanan Web

Ringkasan

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

Places API menawarkan fitur pelengkapan otomatis yang dapat Anda gunakan untuk memberi aplikasi Anda perilaku prediksi penelusuran dari kolom penelusuran Google Maps. Saat pengguna mulai mengetik alamat, pelengkapan otomatis akan mengisi sisanya. Untuk informasi selengkapnya, lihat dokumentasi pelengkapan otomatis.

Memulai

Jika Anda belum memahami Maps JavaScript API atau JavaScript, sebaiknya tinjau JavaScript dan Dapatkan Kunci API sebelum memulai.

Mengaktifkan API

Sebelum menggunakan Places Library di Maps JavaScript API, pastikan terlebih dahulu bahwa Places 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 Places API.
  4. Jika Anda melihat Places API dalam daftar, berarti API tersebut sudah diaktifkan. Jika API tidak tercantum, aktifkan:
    1. Di bagian atas halaman, pilih ENABLE APIS SERVICE untuk menampilkan tab Library. Atau, dari menu samping kiri, pilih Library.
    2. Telusuri Places API, lalu pilih dari daftar hasil.
    3. Pilih AKTIFKAN. Setelah proses ini selesai, Places API akan muncul dalam daftar API di Dashboard.

Memuat Pustaka

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

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Lihat Ringkasan Library untuk informasi selengkapnya.

Tambahkan Places API ke daftar pembatasan API kunci API

Menerapkan pembatasan API ke kunci Anda membatasi penggunaan kunci API untuk satu atau beberapa API atau SDK. Permintaan ke API atau SDK yang terkait dengan kunci API akan diproses. Permintaan ke API atau SDK yang tidak terkait dengan kunci API akan gagal. Guna membatasi kunci API untuk digunakan dengan Places Library, Maps JavaScript API:
  1. Buka Google Cloud Console.
  2. Klik drop-down project lalu pilih project yang berisi kunci API yang ingin Anda amankan.
  3. Klik tombol menu dan pilih Google Maps Platform > Kredensial.
  4. Pada halaman Credentials, klik nama kunci API yang ingin Anda amankan.
  5. Pada halaman Batasi dan ganti nama kunci API, tetapkan batasan:
    • Batasan API
      • Pilih Batasi kunci.
      • Klik Select APIs dan pilih Maps JavaScript API dan Places API.
        (Jika salah satu API tidak tercantum, Anda harus mengaktifkannya.)
  6. Klik SIMPAN.

Kebijakan dan batas penggunaan

Kuota

Places Library, JavaScript API berbagi kuota penggunaan dengan Places API seperti yang dijelaskan dalam dokumentasi Batas Penggunaan untuk Places API. Batas kapasitas kueri per detik diterapkan per sesi pengguna, berapa pun banyaknya pengguna yang berbagi project yang sama.*

Catatan: Saat pertama kali memuat API, kuota awal permintaan akan dialokasikan. Setelah kuota ini digunakan, 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. Untuk permintaan batch, gunakan API layanan web kami.

Kebijakan

Penggunaan Places Library, Maps JavaScript API harus sesuai dengan kebijakan yang dijelaskan untuk Places API.

Place Search

Dengan layanan Places, Anda dapat melakukan jenis penelusuran berikut:

Informasi yang ditampilkan dapat mencakup tempat usaha — seperti restoran, toko, dan kantor — serta 'geocode' hasil, yang menunjukkan alamat, area politik seperti kota besar dan kecil, serta lokasi menarik lainnya.

Permintaan Find Place

Permintaan Find Place memungkinkan Anda menelusuri tempat dengan kueri teks atau nomor telepon. Ada dua jenis permintaan Find Place:

Cari Tempat dari Kueri

Find Place from Query mengambil input teks dan menampilkan tempat. Input dapat berupa jenis data Tempat apa pun, misalnya nama atau alamat bisnis. Untuk membuat permintaan Find Place dari Query, panggil metode findPlaceFromQuery() PlaceService, yang menggunakan parameter berikut:

  • query (wajib) String teks yang digunakan untuk menelusuri, misalnya "restoran" atau "123 Main Street". Ini harus berupa nama tempat, alamat, atau kategori tempat usaha. Jenis input lainnya dapat menghasilkan error dan tidak dijamin akan menampilkan hasil yang valid. Places API akan menampilkan kandidat yang cocok berdasarkan string ini dan mengurutkan hasilnya berdasarkan relevansi yang dirasakan.
  • fields (wajib) Satu atau beberapa kolom yang menentukan jenis data Tempat yang akan ditampilkan.
  • locationBias (opsional) Koordinat yang menentukan area yang akan ditelusuri. Hal ini dapat berupa salah satu dari hal berikut:

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

Contoh berikut menunjukkan panggilan ke findPlaceFromQuery(), menelusuri "Museum of Contemporary Art Australia", dan termasuk kolom name dan geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

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

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

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

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
Lihat contoh

Cari Tempat dari Nomor Telepon

Find Place from Phone Number mengambil nomor telepon dan menampilkan tempat. Untuk membuat permintaan Find Place dari Nomor Telepon, panggil metode findPlaceFromPhoneNumber() PlaceService, yang menggunakan parameter berikut:

  • phoneNumber (wajib diisi) Nomor telepon, dalam format E.164.
  • fields (wajib) Satu atau beberapa kolom yang menentukan jenis data Tempat yang akan ditampilkan.
  • locationBias (opsional) Koordinat yang menentukan area untuk ditelusuri. Hal ini dapat berupa salah satu dari hal berikut:

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

Kolom (metode Find Place)

Gunakan parameter fields untuk menentukan array jenis data tempat yang akan ditampilkan. Contoh: fields: ['formatted_address', 'opening_hours', 'geometry']. Gunakan titik saat menentukan nilai gabungan. Contoh: opening_hours.weekday_text.

Kolom sesuai dengan Hasil Penelusuran Tempat, dan dibagi menjadi tiga kategori penagihan: Dasar, Kontak, dan Atmosfer. Kolom dasar dikenai biaya pada tarif dasar, dan tidak dikenakan biaya tambahan. Kolom Kontak dan Atmosfer ditagih dengan tarif lebih tinggi. Lihat sheet harga untuk mengetahui informasi selengkapnya. Atribusi (html_attributions) selalu ditampilkan bersama setiap panggilan, terlepas dari apakah kolom telah diminta.

Dasar

Kategori Dasar mencakup kolom berikut:
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (tidak digunakan lagi), photos, place_id, plus_code, types

Kontak

Kategori Kontak mencakup kolom berikut: opening_hours
(tidak digunakan lagi di Places Library, Maps JavaScript API. Gunakan permintaan Place Details untuk mendapatkan hasil opening_hours).

Lingkungan

Kategori Atmosfer mencakup kolom berikut: price_level, rating, user_ratings_total

Metode findPlaceFromQuery() dan findPlaceFromPhoneNumber() masing-masing mengambil kumpulan kolom yang sama, dan dapat menampilkan kolom yang sama dalam responsnya masing-masing.

Menetapkan bias lokasi (metode Find Place)

Gunakan parameter locationBias untuk membuat hasil bantuan Find Place di area tertentu. Anda dapat menetapkan locationBias dengan cara berikut:

Bias hasil ke area tertentu:

locationBias: {lat: 37.402105, lng: -122.081974}

Tentukan area persegi panjang untuk ditelusuri:

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

Anda juga dapat menggunakan LatLngBounds.

Tentukan radius yang akan ditelusuri (dalam meter), yang berpusat pada area tertentu:

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Permintaan Nearby Search

Nearby Search memungkinkan Anda menelusuri tempat dalam area yang ditetapkan berdasarkan kata kunci atau jenis. Nearby Search harus selalu menyertakan lokasi, yang dapat ditentukan dengan salah satu dari dua cara berikut:

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

Penelusuran Places Nearby dimulai dengan panggilan ke metode nearbySearch() PlacesService, yang akan menampilkan array objek PlaceResult. Perhatikan bahwa metode nearbySearch() menggantikan metode search() pada 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, yang harus berupa objek google.maps.LatLngBounds yang menentukan area penelusuran persegi panjang; atau
    • location dan radius; yang pertama mengambil objek google.maps.LatLng, dan yang terakhir mengambil bilangan bulat sederhana, yang mewakili radius lingkaran dalam meter. Radius maksimum yang diizinkan adalah 50.000 meter. Perhatikan bahwa saat rankBy ditetapkan ke DISTANCE, Anda harus menentukan location, tetapi Anda tidak dapat menentukan radius atau bounds.
  • keyword (opsional) — Istilah yang akan dicocokkan dengan semua kolom yang tersedia, termasuk tetapi tidak terbatas pada nama, jenis, dan alamat, serta ulasan pelanggan dan konten pihak ketiga lainnya.
  • minPriceLevel dan maxPriceLevel (opsional) — Membatasi hasil hanya untuk tempat yang berada dalam rentang yang ditentukan. Nilai yang valid berkisar antara 0 (paling terjangkau) hingga 4 (paling mahal), inklusif.
  • name Tidak digunakan lagi. Setara dengan keyword. Nilai di kolom ini digabungkan dengan nilai di kolom keyword dan diteruskan sebagai bagian dari string penelusuran yang sama.
  • openNow (opsional) — Nilai boolean, yang menunjukkan bahwa layanan Places hanya boleh menampilkan tempat yang buka untuk bisnis pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan ditampilkan jika Anda menyertakan parameter ini dalam kueri. Menyetel openNow ke false tidak akan berpengaruh.
  • rankBy (opsional) — Menentukan urutan daftar hasil. Nilainya dapat berupa:
    • google.maps.places.RankBy.PROMINENCE (default). Opsi ini mengurutkan hasil berdasarkan tingkat kepentingannya. Peringkat akan mengutamakan tempat yang menonjol dalam radius yang ditetapkan daripada tempat terdekat yang cocok, tetapi kurang menonjol. Keterlihatan dapat dipengaruhi oleh peringkat tempat dalam indeks Google, popularitas global, dan faktor lainnya. Jika google.maps.places.RankBy.PROMINENCE ditentukan, parameter radius diperlukan.
    • google.maps.places.RankBy.DISTANCE. Opsi ini akan mengurutkan hasil dalam urutan menaik menurut jaraknya dari location yang ditentukan (wajib). Perhatikan bahwa Anda tidak dapat menentukan bounds dan/atau radius kustom jika Anda menentukan RankBy.DISTANCE. Saat Anda menentukan RankBy.DISTANCE, satu atau beberapa keyword, name, atau type diperlukan.
  • type — Membatasi hasil ke tempat yang cocok dengan jenis yang ditentukan. Hanya satu jenis yang dapat ditentukan (jika lebih dari satu jenis disediakan, semua jenis setelah entri pertama akan diabaikan). Lihat daftar jenis yang didukung.

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',
    type: ['restaurant']
  };

  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++) {
      createMarker(results[i]);
    }
  }
}

Lihat contoh

Permintaan Text Search

Layanan Google Places Text Search adalah layanan web yang menampilkan informasi tentang sekumpulan tempat berdasarkan string — misalnya "pizza di New York" atau "toko sepatu dekat Ottawa". Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan bias lokasi apa pun yang telah ditetapkan. Respons penelusuran akan menyertakan daftar tempat. Anda dapat mengirim permintaan Place Details untuk mengetahui informasi selengkapnya tentang tempat dalam respons.

Text Search dimulai 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 (wajib) String teks yang digunakan untuk menelusuri, misalnya: "restoran" atau "123 Main Street". Ini harus berupa nama tempat, alamat, atau kategori tempat usaha. Jenis input lainnya dapat menghasilkan error dan tidak dijamin akan menampilkan hasil yang valid. Layanan Places akan menampilkan kecocokan kandidat berdasarkan string ini dan mengurutkan hasilnya berdasarkan relevansi yang terlihat. Parameter ini menjadi opsional jika parameter type juga digunakan dalam permintaan penelusuran.
  • Secara opsional:
    • openNow — Nilai boolean, yang menunjukkan bahwa layanan Places hanya boleh menampilkan tempat yang buka untuk bisnis pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan ditampilkan jika Anda menyertakan parameter ini dalam kueri. Menyetel openNow ke false tidak akan berpengaruh.
    • minPriceLevel dan maxPriceLevel — Membatasi hasil hanya ke tempat yang berada dalam tingkat harga yang ditentukan. Nilai yang valid berkisar dari 0 (paling terjangkau) hingga 4 (paling mahal), inklusif.
    • Salah satu dari:
      • bounds — Objek google.maps.LatLngBounds yang menentukan persegi panjang untuk ditelusuri; atau
      • location dan radius — Anda dapat mencondongkan hasil ke lingkaran yang ditentukan dengan meneruskan parameter location dan radius. Hal ini akan menginstruksikan layanan Places agar lebih memilih untuk menampilkan hasil dalam lingkaran tersebut. Hasil di luar area yang didefinisikan mungkin tetap ditampilkan. Lokasi akan mengambil objek google.maps.LatLng, dan radius mengambil bilangan bulat sederhana, yang mewakili radius lingkaran dalam meter. Radius maksimum yang diperbolehkan adalah 50.000 meter.
    • type — Membatasi hasil ke tempat yang cocok dengan jenis yang ditentukan. Hanya satu jenis yang dapat ditentukan (jika lebih dari satu jenis disediakan, semua jenis setelah entri pertama akan diabaikan). Lihat daftar jenis yang didukung.

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]);
    }
  }
}

Respons Penelusuran

Kode Status

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

  • INVALID_REQUEST: Permintaan ini tidak valid.
  • OK: Respons berisi hasil yang valid.
  • OVER_QUERY_LIMIT: Halaman web telah melampaui kuota permintaannya.
  • REQUEST_DENIED: Halaman web tidak diizinkan untuk menggunakan PlacesService.
  • UNKNOWN_ERROR: Permintaan PlacesService tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.
  • ZERO_RESULTS: Tidak ditemukan hasil untuk permintaan ini.

Hasil Place Search

Fungsi findPlace(), nearbySearch(), dan textSearch() menampilkan array objek PlaceResult.

Setiap objek PlaceResult dapat menyertakan properti berikut:

  • business_status menunjukkan status operasional tempat, jika berupa bisnis. Dapat berisi salah satu dari nilai berikut ini:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Jika tidak ada data, business_status tidak akan ditampilkan.
  • formatted_address adalah string yang berisi alamat tempat yang dapat dibaca manusia untuk tempat ini. Properti formatted_address hanya ditampilkan untuk Penelusuran Teks.

    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.

  • geometry: Informasi terkait geometri tempat. Hal ini mencakup:
    • location memberikan lintang dan bujur tempat tersebut.
    • viewport menentukan area pandang yang diinginkan pada peta saat melihat tempat ini.
  • permanently_closed (tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut telah dinonaktifkan secara permanen atau sementara (nilai true). Jangan gunakan permanently_closed. Sebagai gantinya, gunakan business_status untuk mendapatkan status operasional bisnis.
  • plus_code (lihat Kode Lokasi Terbuka dan kode plus) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8.000 derajat dengan 1/8.000 derajat (sekitar 14 x 14 m di ekuator) atau lebih kecil. Plus Codes dapat digunakan sebagai pengganti alamat di tempat yang tidak ada (tempat bangunan tidak diberi nomor atau jalan tidak diberi nama).

    Plus Codes diformat sebagai kode global dan kode gabungan:

    • global_code adalah kode area berisi 4 karakter dan kode lokal berisi 6 karakter atau lebih (849VCWC8+R9).
    • compound_code adalah kode lokal berisi 6 karakter atau lebih dengan lokasi yang eksplisit (CWC8+R9, Mountain View, CA, USA). Jangan mengurai konten ini secara terprogram.
    Biasanya, kode global dan kode gabungan ditampilkan. Namun, jika hasilnya berada di lokasi terpencil (misalnya, lautan atau gurun), hanya kode global yang dapat ditampilkan.
  • html_attributions: Array atribusi yang harus Anda tampilkan saat menampilkan hasil penelusuran. Setiap entri dalam array berisi teks HTML untuk satu atribusi. Catatan: Ini adalah kumpulan semua atribusi untuk seluruh respons penelusuran. Oleh karena itu, semua objek PlaceResult dalam respons berisi daftar atribusi yang identik.
  • icon menampilkan URL untuk ikon PNG berwarna 71px x 71px.
  • icon_mask_base_uri menampilkan URL dasar untuk ikon tidak berwarna, tanpa ekstensi .svg atau .png.
  • icon_background_color menampilkan kode warna HEX default untuk kategori tempat.
  • name: Nama tempat.
  • opening_hours dapat berisi informasi berikut:
    • open_now adalah nilai boolean yang menunjukkan apakah tempat tersebut buka pada saat ini (Tidak digunakan lagi di Places Library, Maps JavaScript API, menggunakan utc_offset_minutes sebagai gantinya).
  • place_id adalah ID tekstual yang secara unik mengidentifikasi tempat. Untuk mengambil informasi tentang tempat, teruskan ID ini dalam permintaan Place Details . Pelajari lebih lanjut cara mereferensikan tempat dengan ID tempat.
  • rating berisi rating tempat, dari 0,0 hingga 5,0, berdasarkan ulasan pengguna gabungan.
  • types Array jenis untuk tempat ini (misalnya, ["political", "locality"] atau ["restaurant", "lodging"]. Array ini dapat berisi beberapa nilai, atau mungkin kosong. Nilai baru dapat diperkenalkan tanpa pemberitahuan sebelumnya. Lihat daftar jenis yang didukung.
  • vicinity: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor jalan, dan lokalitas, tetapi tidak termasuk provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilai vicinity sebesar 5/48 Pirrama Road, Pyrmont.

Mengakses Hasil Tambahan

Secara default, setiap penelusuran tempat mengembalikan hingga 20 hasil per kueri. Namun, setiap penelusuran dapat menampilkan sebanyak 60 hasil, yang dibagi menjadi tiga halaman. Halaman tambahan tersedia melalui objek PlaceSearchPagination. Untuk mengakses halaman tambahan, Anda harus mengambil objek PlaceSearchPagination melalui fungsi callback. Objek PlaceSearchPagination ditentukan sebagai:

  • hasNextPage properti boolean yang menunjukkan apakah tersedia hasil lebih lanjut. true saat ada halaman hasil tambahan.
  • nextPage() fungsi yang akan menampilkan kumpulan hasil berikutnya. Setelah menjalankan penelusuran, Anda harus menunggu dua detik sebelum halaman hasil berikutnya akan tersedia.

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

Contoh di bawah menunjukkan cara mengubah fungsi callback untuk mengambil objek PlaceSearchPagination sehingga Anda dapat mengeluarkan beberapa permintaan penelusuran.

TypeScript

// 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">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

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

JavaScript

// 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">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const 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),
      };

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

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
Lihat contoh

Coba Sampel

Place Details

Selain menyediakan daftar tempat dalam suatu area, layanan Places juga dapat menampilkan informasi mendetail tentang tempat tertentu. Setelah tempat ditampilkan dalam respons penelusuran tempat, ID tempatnya dapat digunakan untuk meminta detail tambahan tentang tempat tersebut, seperti alamat lengkap, nomor telepon, rating pengguna dan ulasannya, dll.

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 tempat yang diinginkan, dan kolom yang menunjukkan jenis data Tempat yang akan ditampilkan. Pelajari lebih lanjut cara mereferensikan 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',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

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

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

Lihat contoh

Kolom (Detail tempat)

Parameter fields menggunakan array string (nama kolom).

Gunakan parameter fields untuk menentukan array jenis data tempat yang akan ditampilkan. Contoh: fields: ['address_component', 'opening_hours', 'geometry']. Gunakan titik saat menentukan nilai gabungan. Contoh: opening_hours.weekday_text.

Kolom sesuai dengan hasil Place Details, dan dibagi menjadi tiga kategori penagihan: Basic, Contact, dan Atmosphere. Kolom dasar ditagih dengan tarif dasar, dan tidak dikenakan biaya tambahan. Kolom Kontak dan Atmosfer ditagih dengan tarif yang lebih tinggi. Lihat sheet harga untuk mengetahui informasi selengkapnya. Atribusi (html_attributions) selalu ditampilkan bersama setiap panggilan, terlepas dari apakah permintaan telah diminta.

Dasar

Kategori Dasar mencakup kolom berikut:
address_component, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (tidak digunakan lagi), photo, place_id, plus_code, type, url, utc_offset (tidak digunakan lagi di Places

Kontak

Kategori Kontak mencakup kolom berikut:
formatted_phone_number, international_phone_number, opening_hours, website

Lingkungan

Kategori Atmosfer mencakup kolom berikut: price_level, rating, review, user_ratings_total

Pelajari kolom tempat lebih lanjut. Untuk informasi selengkapnya tentang cara penagihan permintaan data Tempat, lihat Penggunaan dan Penagihan.

Respons Place Details

Kode Status

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

  • INVALID_REQUEST: Permintaan ini tidak valid.
  • OK: Respons berisi hasil yang valid.
  • OVER_QUERY_LIMIT: Halaman web telah melampaui kuota permintaannya.
  • NOT_FOUND Lokasi yang direferensikan tidak ditemukan dalam database Tempat.
  • REQUEST_DENIED: Halaman web tidak diizinkan untuk menggunakan PlacesService.
  • UNKNOWN_ERROR: Permintaan PlacesService tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.
  • ZERO_RESULTS: Tidak ditemukan hasil untuk permintaan ini.

Hasil Place Details

Panggilan getDetails() yang berhasil akan menampilkan objek PlaceResult dengan properti berikut:

  • address_components: 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.
  • business_status menunjukkan status operasional tempat, jika berupa bisnis. Dapat berisi salah satu dari nilai berikut ini:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Jika tidak ada data, business_status tidak akan ditampilkan.
  • formatted_address: Alamat tempat 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.

  • formatted_phone_number: Nomor telepon tempat, yang diformat sesuai dengan konvensi regional nomor.
  • geometry: Informasi terkait geometri tempat. Hal ini mencakup:
    • location memberikan lintang dan bujur tempat tersebut.
    • viewport menentukan area pandang yang diinginkan pada peta saat melihat tempat ini.
  • permanently_closed (tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut telah dinonaktifkan secara permanen atau sementara (nilai true). Jangan gunakan permanently_closed. Sebagai gantinya, gunakan business_status untuk mendapatkan status operasional bisnis.
  • plus_code (lihat Kode Lokasi Terbuka dan kode plus) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8.000 derajat dengan 1/8.000 derajat (sekitar 14 x 14 m di ekuator) atau lebih kecil. Plus Codes dapat digunakan sebagai pengganti alamat di tempat yang tidak ada (tempat bangunan tidak diberi nomor atau jalan tidak diberi nama).

    Plus Codes diformat sebagai kode global dan kode gabungan:

    • global_code adalah kode area berisi 4 karakter dan kode lokal berisi 6 karakter atau lebih (849VCWC8+R9).
    • compound_code adalah kode lokal berisi 6 karakter atau lebih dengan lokasi yang eksplisit (CWC8+R9, Mountain View, CA, USA). Jangan mengurai konten ini secara terprogram.
    Biasanya, kode global dan kode gabungan ditampilkan. Namun, jika hasilnya berada di lokasi terpencil (misalnya, lautan atau gurun), hanya kode global yang dapat ditampilkan.
  • html_attributions: Teks atribusi yang akan ditampilkan untuk hasil tempat ini.
  • icon: URL ke resource gambar yang dapat digunakan untuk mewakili jenis tempat 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 Tidak digunakan lagi di Places Library, Maps JavaScript API, menggunakan utc_offset_minutes sebagai gantinya.
  • utc_offset_minutes berisi jumlah menit zona waktu tempat ini saat ini di-offset dari UTC. Misalnya, untuk tempat di Sydney, Australia selama waktu musim panas, nilainya akan 660 (+11 jam dari UTC), dan untuk tempat di California di luar waktu musim panas, nilainya akan menjadi -480 (-8 jam dari UTC).
  • opening_hours berisi informasi berikut:
    • open_now (Tidak digunakan lagi di Places Library, Maps JavaScript API; gunakan opening_hours.isOpen(). Tonton video ini untuk mengetahui cara menggunakan isOpen dengan Place Details.) adalah nilai boolean yang menunjukkan apakah tempat tersebut buka pada waktu saat ini.
    • periods[] adalah array periode buka yang mencakup tujuh hari, dimulai dari hari Minggu, dalam urutan kronologis. Setiap periode berisi:
      • open berisi sepasang objek hari dan waktu yang menjelaskan kapan tempat tersebut dibuka:
        • day angka dari 0–6, yang terkait dengan hari dalam seminggu, mulai hari Minggu. Misalnya, 2 berarti Selasa.
        • time dapat berisi waktu dalam sehari dalam format 24 jam hhmm (nilainya berada pada rentang 0.000–2359). time akan dilaporkan dalam zona waktu tempat tersebut.
      • close dapat berisi sepasang objek hari dan waktu yang menjelaskan kapan tempat tersebut tutup. Catatan: Jika tempat selalu buka, bagian close akan hilang dari respons. Aplikasi dapat selalu menggunakan representasi terbuka sebagai periode open yang berisi day dengan nilai 0 dan time dengan nilai 0000, dan tanpa close.
    • weekday_text adalah array tujuh string yang mewakili jam buka yang diformat untuk setiap hari dalam seminggu. Jika parameter language ditentukan dalam permintaan Place Details, Places Service akan memformat dan melokalkan jam buka sesuai bahasa tersebut. Urutan elemen dalam array ini bergantung pada parameter language. Beberapa bahasa dimulai seminggu pada hari Senin sementara bahasa lainnya dimulai pada hari Minggu.
  • permanently_closed (tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut telah dinonaktifkan secara permanen atau sementara (nilai true). Jangan gunakan permanently_closed. Sebagai gantinya, gunakan business_status untuk mendapatkan status operasional bisnis.
  • photos[]: array objek PlacePhoto. PlacePhoto dapat digunakan untuk mendapatkan foto dengan metode getUrl(), atau Anda dapat memeriksa objek tersebut untuk nilai berikut:
    • height: tinggi maksimum gambar, dalam piksel.
    • width: lebar maksimum gambar, dalam piksel.
    • html_attributions: Teks atribusi yang akan ditampilkan dengan foto tempat ini.
  • place_id: ID tekstual yang secara unik mengidentifikasi tempat dan dapat digunakan untuk mengambil informasi tentang tempat melalui permintaan Place Details. Pelajari lebih lanjut cara mereferensikan tempat dengan ID tempat.
  • rating: Rating tempat, dari 0,0 hingga 5,0, berdasarkan ulasan pengguna gabungan.
  • reviews array yang dapat berisi hingga lima ulasan. Setiap ulasan terdiri dari beberapa komponen:
    • aspects[] berisi array objek PlaceAspectRating, yang masing-masing memberikan rating satu atribut tempat usaha. Objek pertama dalam array dianggap sebagai aspek utama. Setiap PlaceAspectRating ditentukan sebagai:
      • type nama aspek yang sedang diberi rating. Jenis-jenis berikut didukung: appeal, atmosphere, decor, facilities, food, overall, quality, dan service.
      • rating rating dari pengguna untuk aspek tertentu, dari 0 hingga 3.
    • author_name nama pengguna yang mengirimkan ulasan. Ulasan anonim diatribusikan ke "Pengguna Google". Jika parameter bahasa telah ditetapkan, frasa "Pengguna Google" akan menampilkan string yang dilokalkan.
    • author_url URL ke profil Google+ pengguna, jika tersedia.
    • language kode bahasa IETF yang menunjukkan bahasa yang digunakan dalam ulasan pengguna. Kolom ini hanya berisi tag bahasa utama, bukan tag sekunder yang menunjukkan negara atau wilayah. Misalnya, semua ulasan dalam bahasa Inggris diberi tag sebagai 'en', dan bukan 'en-AU' atau 'en-UK' dan seterusnya.
    • rating rating keseluruhan untuk tempat ini. Ini adalah bilangan bulat, mulai dari 1 hingga 5.
    • text dari ulasan pengguna. Saat mengulas lokasi dengan Google Places, ulasan teks dianggap opsional; oleh karena itu, kolom ini mungkin kosong.
  • types Array jenis untuk tempat ini (misalnya, ["political", "locality"] atau ["restaurant", "lodging"]. Array ini dapat berisi beberapa nilai, atau mungkin kosong. Nilai baru dapat diperkenalkan tanpa pemberitahuan sebelumnya. Lihat daftar jenis yang didukung.
  • url: URL halaman Google resmi untuk tempat ini. Ini adalah halaman milik Google yang berisi informasi terbaik yang tersedia tentang tempat tersebut. Aplikasi harus menautkan atau menyematkan halaman ini pada layar apa pun yang menampilkan hasil detail tentang tempat tersebut kepada pengguna.
  • vicinity: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor jalan, dan lokalitas, tetapi tidak termasuk provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilai vicinity sebesar 5/48 Pirrama Road, Pyrmont. Properti vicinity hanya ditampilkan untuk Penelusuran Langsung.
  • website mencantumkan situs resmi untuk tempat ini, seperti halaman beranda bisnis.

Catatan: Rating multidimensi mungkin tidak tersedia untuk semua lokasi. Jika ulasan terlalu sedikit, respons detail akan menyertakan rating lama dengan skala 0,0 hingga 5,0 (jika tersedia) atau tanpa rating sama sekali.

Mereferensikan sebuah Tempat dengan ID Tempat

ID tempat adalah referensi unik ke sebuah tempat di Google Maps. Place ID tersedia untuk sebagian besar lokasi, termasuk lokasi bisnis, tempat terkenal, taman, dan persimpangan.

Untuk menggunakan ID tempat di aplikasi, Anda harus terlebih dahulu mencari ID, yang tersedia di PlaceResult permintaan Place Search atau Details. Anda kemudian dapat menggunakan ID tempat ini untuk mencari Place Details.

ID tempat dikecualikan dari pembatasan penyimpanan dalam cache yang disebutkan dalam Pasal 3.2.3(a) dalam Persyaratan Layanan Google Maps Platform. Karena itu Anda bisa menyimpan nilai ID tempat untuk digunakan nanti. Untuk praktik terbaik saat menyimpan ID tempat, lihat ringkasan ID tempat.

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);

Foto Tempat

Fitur Place Photo memungkinkan Anda menambahkan konten fotografi berkualitas tinggi ke situs Anda. Layanan Foto memberi Anda akses ke jutaan foto yang tersimpan di database Tempat dan Google+ Lokal. Saat Anda mendapatkan informasi tempat menggunakan permintaan Place Details, referensi foto akan ditampilkan untuk konten fotografi yang relevan. Permintaan Nearby Search dan Text Search juga menampilkan satu referensi foto per tempat, jika relevan. Dengan layanan Foto, Anda dapat mengakses foto yang direferensikan dan mengubah ukuran gambar ke ukuran optimal untuk aplikasi Anda.

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

Catatan: Jumlah foto yang ditampilkan bervariasi berdasarkan permintaan.

  • Penelusuran di Sekitar atau Penelusuran Teks akan menampilkan maksimal satu objek PlacePhoto.
  • Permintaan Details akan menampilkan hingga sepuluh objek PlacePhoto.

Anda dapat meminta URL untuk gambar terkait dengan memanggil metode PlacePhoto.getUrl(), serta meneruskan objek PhotoOptions yang valid. Objek PhotoOptions memungkinkan Anda menentukan tinggi dan lebar maksimum yang diinginkan dari gambar. Jika Anda menentukan nilai untuk maxHeight dan maxWidth, layanan foto akan mengubah ukuran gambar menjadi lebih kecil dari kedua ukuran tersebut, dengan tetap mempertahankan rasio lebar tinggi asli.

Cuplikan kode berikut menerima objek tempat, dan menambahkan penanda ke peta jika foto ada. Gambar penanda default diganti dengan versi kecil 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})
  });
}

Foto yang ditampilkan oleh layanan Foto berasal dari berbagai lokasi, termasuk foto pemilik bisnis dan kontribusi pengguna. Dalam sebagian besar kasus, foto-foto ini dapat digunakan tanpa atribusi, atau akan menyertakan atribusi yang diperlukan sebagai bagian dari gambar. Namun, jika elemen photo yang ditampilkan menyertakan nilai di kolom html_attributions, Anda harus menyertakan atribusi tambahan dalam aplikasi di mana pun Anda menampilkan gambar.