Library Places

Ringkasan

Fungsi di Library Places, Maps JavaScript API memungkinkan aplikasi Anda menelusuri tempat (didefinisikan dalam API ini sebagai tempat usaha, lokasi geografis, atau lokasi menarik terkemuka) 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 memberikan aplikasi Anda perilaku prediksi penelusuran pada kolom penelusuran Google Maps. Saat pengguna mulai mengetik alamat, pelengkapan otomatis akan mengisikan sisanya. Untuk mengetahui informasi selengkapnya, lihat dokumentasi pelengkapan otomatis.

Memulai

Jika belum memahami Maps JavaScript API atau JavaScript, sebaiknya Anda meninjau JavaScript dan Mendapatkan Kunci API sebelum memulai.

Mengaktifkan API

Sebelum menggunakan Library Places di Maps JavaScript API, pastikan terlebih dahulu Places API diaktifkan di Konsol Google Cloud, dalam project yang sama 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 Dashboard, 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 AND SERVICES untuk menampilkan tab Library. Atau, dari menu samping kiri, pilih Library.
    2. Telusuri Places API, lalu pilih dari daftar hasil.
    3. Pilih ENABLE. Setelah proses ini selesai, Places API akan muncul dalam daftar API di Dashboard.

Memuat library

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

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

Lihat Ringkasan Library untuk informasi selengkapnya.

Menambahkan Places API ke daftar pembatasan API untuk kunci API

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

Kebijakan dan batas penggunaan

Kuota

Library Places berbagi kuota penggunaan dengan Places API seperti yang dijelaskan dalam dokumentasi Batas Penggunaan untuk Places API.

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 hasil 'geocode', yang menunjukkan alamat, area politik seperti kota kecil dan kota besar, 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:

Find Place from Query

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

  • query (wajib) String teks yang digunakan untuk menelusuri, misalnya: "restaurant" atau "123 Main Street". String 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 hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.
  • fields (wajib) Satu atau beberapa kolom yang menentukan jenis data Tempat yang akan ditampilkan.
  • locationBias (opsional) Koordinat yang menentukan area yang akan ditelusuri. Koordinat ini bisa berupa salah satu dari yang berikut:
    • Kumpulan koordinat lintang/bujur yang ditentukan sebagai LatLngLiteral atau objek LatLng
    • Batas persegi panjang (dua pasangan lintang/bujur, atau objek LatLngBounds)
    • Radius (dalam meter) yang berpusat pada lintang/bujur

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

Contoh berikut menunjukkan panggilan ke findPlaceFromQuery(), yang menelusuri "Museum of Contemporary Art Australia", dan menyertakan 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

Find Place from Phone Number

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

  • phoneNumber (wajib) 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 yang akan ditelusuri. Koordinat ini bisa berupa salah satu dari yang berikut:
    • Kumpulan koordinat lintang/bujur yang ditentukan sebagai LatLngLiteral atau objek LatLng
    • Batas persegi panjang (empat titik lintang/bujur atau objek LatLngBounds)
    • Radius (dalam meter) yang berpusat pada lintang/bujur

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 Place Search, dan dibagi menjadi tiga kategori penagihan: Basic, Contact, dan Atmosphere. Kolom Basic ditagih dengan tarif dasar dan tidak dikenai biaya tambahan. Kolom Contact dan Atmosphere ditagih dengan tarif lebih tinggi. Lihat sheet harga untuk mengetahui informasi selengkapnya. Atribusi (html_attributions) selalu ditampilkan dengan setiap panggilan, terlepas dari apakah kolom telah diminta atau tidak.

Basic

Kategori Basic 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

Contact

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

Atmosphere

Kategori Atmosphere mencakup kolom berikut: price_level, rating, user_ratings_total

Metode findPlaceFromQuery() dan findPlaceFromPhoneNumber() masing-masing menggunakan 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 Find Place mendukung hasil di area tertentu. Anda dapat menetapkan locationBias dengan cara berikut:

Membiaskan hasil ke area tertentu:

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

Menentukan area persegi panjang yang akan ditelusuri:

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

Anda juga dapat menggunakan LatLngBounds.

Menentukan 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 dengan kata kunci atau jenis. Nearby Search harus selalu menyertakan lokasi, yang bisa ditetapkan dalam salah satu dari dua cara berikut:

  • LatLngBounds.
  • area melingkar yang didefinisikan sebagai kombinasi dari 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 PlaceResult. Perhatikan bahwa 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 kolom berikut:

  • Salah satu dari:
    • bounds, yang harus berupa Objek google.maps.LatLngBounds yang menentukan persegi panjang area penelusuran. Jarak diagonal maksimum yang didukung untuk batas luasnya sekitar 100.000 meter.
    • location dan radius; yang pertama menggunakan objek google.maps.LatLng, dan yang kedua menggunakan bilangan bulat sederhana yang menampilkan radius lingkaran dalam meter. Maksimum radius 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 ke 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 sedang buka pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan ditampilkan jika Anda menyertakan parameter ini dalam kueri. Menetapkan openNow ke false tidak akan berpengaruh.
  • rankBy (opsional) — Menentukan urutan daftar hasil. Nilainya dapat berupa:
    • google.maps.places.RankBy.PROMINENCE (default). Opsi ini menyortir hasil menurut tingkat kepentingannya. Peringkat akan mengutamakan tempat terkemuka dalam radius yang telah ditentukan dibandingkan tempat terdekat yang cocok tetapi kurang terkemuka. Tempat terkemuka bisa dipengaruhi oleh peringkat suatu tempat dalam indeks Google, popularitas global, dan faktor lainnya. Jika google.maps.places.RankBy.PROMINENCE ditentukan, parameter radius wajib diisi.
    • google.maps.places.RankBy.DISTANCE. Opsi ini mengurutkan hasil dalam urutan menaik berdasarkan jaraknya dari location yang telah 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 serangkaian tempat berdasarkan suatu string — misalnya "pizza di Bandung" atau "toko sepatu dekat Solo". Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan bias lokasi yang telah ditetapkan. Respons penelusuran akan menyertakan daftar tempat. Anda bisa mengirim permintaan Place Details untuk informasi selengkapnya tentang tempat dalam respons tersebut.

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 kolom berikut:

  • query (wajib) String teks yang digunakan untuk menelusuri tempat, misalnya: "restaurant" atau "123 Main Street". String 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 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 — Nilai boolean, yang menunjukkan bahwa layanan Places hanya boleh menampilkan tempat yang sedang buka pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan ditampilkan jika Anda menyertakan parameter ini dalam kueri. Menetapkan 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, yang harus berupa Objek google.maps.LatLngBounds yang menentukan persegi panjang area penelusuran. Jarak diagonal maksimum yang didukung untuk batas luasnya sekitar 100.000 meter.
      • location dan radius — Anda dapat membiaskan hasil ke lingkaran yang ditentukan dengan meneruskan parameter location dan radius. Cara ini akan menginstruksikan layanan Places agar memprioritaskan untuk menampilkan hasil dalam lingkaran tersebut. Hasil di luar area yang didefinisikan mungkin tetap ditampilkan. Lokasi menggunakan objek google.maps.LatLng, dan radius menggunakan bilangan bulat sederhana, yang menampilkan radius lingkaran dalam meter. Radius maksimum yang diizinkan adalah 50.000 meter.
    • type — Membatasi hasil ke tempat yang cocok dengan jenis yang ditentukan. Hanya satu jenis yang boleh ditetapkan (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 kegagalan 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 menggunakan PlacesService.
  • UNKNOWN_ERROR: Permintaan PlacesService tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.
  • ZERO_RESULTS: Tidak ada hasil yang ditemukan 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. Properti ini dapat berisi salah satu dari nilai berikut:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Jika tidak ada data, business_status tidak akan ditampilkan.
  • formatted_address adalah string yang berisi alamat tempat ini yang dapat dibaca orang. Properti formatted_address hanya ditampilkan untuk Text Search.

    Sering kali alamat ini sama dengan alamat pos. Harap ingat 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 atas 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 yang terkait dengan geometri suatu tempat. Hal ini mencakup:
    • location memberikan garis lintang dan bujur suatu tempat.
    • viewport menentukan area pandang yang diinginkan pada peta saat menampilkan tempat ini.
  • permanently_closed (tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut tutup permanen atau sementara waktu (nilai true). Jangan gunakan permanently_closed. Sebagai gantinya, gunakan business_status untuk mendapatkan status operasional bisnis.
  • plus_code (lihat Open Location Code dan Plus Codes) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8000 derajat x 1/8000 derajat (sekitar 14 m x 14 m di khatulistiwa) atau lebih kecil. Plus Codes dapat digunakan sebagai pengganti alamat di tempat tanpa alamat jelas (jika 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, samudra 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 atribusi tunggal. Catatan: Array 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 dengan ukuran 71x71 piksel.
  • icon_mask_base_uri menampilkan URL dasar untuk ikon tidak berwarna, tanpa ekstensi .svg atau .png.
  • icon_background_color menampilkan kode warna heksadesimal 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 Library Places, Maps JavaScript API, gunakan 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 gabungan ulasan pengguna.
  • types Array jenis untuk tempat ini (misalnya, ["political", "locality"] atau ["restaurant", "lodging"]). Array ini dapat berisi beberapa nilai, atau mungkin kosong. Nilai baru dapat dimasukkan tanpa pemberitahuan sebelumnya. Lihat daftar jenis yang didukung.
  • vicinity: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor gedung, dan lokalitas, tetapi bukan provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilai vicinity berupa 5/48 Pirrama Road, Pyrmont.

Mengakses Hasil Tambahan

Secara default, setiap penelusuran tempat menampilkan hingga 20 hasil per kueri. Namun, setiap penelusuran dapat menampilkan hingga 60 hasil, yang terbagi dalam tiga halaman. Halaman tambahan tersedia melalui objek PlaceSearchPagination. Untuk mengakses halaman tambahan, Anda harus mengambil objek PlaceSearchPagination melalui fungsi callback. Objek PlaceSearchPagination didefinisikan 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, 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;
index.ts

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;
index.js
Lihat contoh

Mencoba Contoh

Place Details

Selain menyediakan daftar tempat dalam suatu area, layanan Places juga menampilkan informasi detail tentang tempat tertentu. Setelah tempat ditampilkan dalam respons penelusuran tempat, ID tempat dapat digunakan untuk meminta detail tambahan tentang tempat tersebut, seperti alamat lengkap, nomor telepon, rating pengguna, ulasan pengguna, 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 menggunakan permintaan, yang berisi placeId untuk tempat yang diinginkan, dan kolom yang menunjukkan jenis data Places yang akan ditampilkan. Pelajari lebih lanjut cara mereferensikan tempat dengan ID tempat.

Cara 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 (Place Details)

Parameter fields menggunakan array string (nama kolom).

Gunakan parameter fields untuk menentukan array jenis data tempat yang akan ditampilkan. Contoh: fields: ['address_components', '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 Basic ditagih dengan tarif dasar dan tidak dikenai biaya tambahan. Kolom Contact dan Atmosphere ditagih dengan tarif lebih tinggi. Lihat sheet harga untuk mengetahui informasi selengkapnya. Atribusi (html_attributions) selalu ditampilkan dengan setiap panggilan, terlepas dari apakah kolom telah diminta atau tidak.

Basic

Kategori Basic mencakup kolom berikut:
address_components, 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 Library Places, Maps JavaScript API), utc_offset_minutes, vicinity

Contact

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

Atmosphere

Kategori Atmosphere mencakup kolom berikut: price_level, rating, reviews, 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 kegagalan 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 dirujuk tidak ditemukan dalam database Tempat.
  • REQUEST_DENIED: Halaman web tidak diizinkan menggunakan PlacesService.
  • UNKNOWN_ERROR: Permintaan PlacesService tidak dapat diproses karena error 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 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 "AK" menggunakan 2 huruf singkatan istilah pos.

    Perhatikan fakta berikut tentang array address_components[] :

    • Array komponen alamat dapat berisi lebih banyak komponen daripada formatted_address.
    • Array tidak harus selalu menyertakan semua entitas 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, yang 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 dalam array. Jenis komponen dapat berubah. Komponen tertentu mungkin tidak ada dalam respons berikutnya.
  • business_status menunjukkan status operasional tempat, jika berupa bisnis. Properti ini dapat berisi salah satu dari nilai berikut:
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Jika tidak ada data, business_status tidak akan ditampilkan.
  • formatted_address: Alamat tempat ini yang dapat dibaca orang.

    Sering kali alamat ini sama dengan alamat pos. Harap ingat 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 atas 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 penomoran di wilayah tersebut.
  • geometry: Informasi yang terkait dengan geometri suatu tempat. Hal ini mencakup:
    • location memberikan garis lintang dan bujur suatu tempat.
    • viewport menentukan area pandang yang diinginkan pada peta saat menampilkan tempat ini.
  • permanently_closed (tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut tutup permanen atau sementara waktu (nilai true). Jangan gunakan permanently_closed. Sebagai gantinya, gunakan business_status untuk mendapatkan status operasional bisnis.
  • plus_code (lihat Open Location Code dan Plus Codes) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8000 derajat x 1/8000 derajat (sekitar 14 m x 14 m di khatulistiwa) atau lebih kecil. Plus Codes dapat digunakan sebagai pengganti alamat di tempat tanpa alamat jelas (jika 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, samudra 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 bisa digunakan untuk menampilkan 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, gunakan utc_offset_minutes sebagai gantinya.
  • utc_offset_minutes berisi offset jumlah menit antara zona waktu tempat ini sekarang dari UTC. Misalnya, untuk tempat di Sydney, Australia saat terjadi penyesuaian waktu musim panas akan menjadi 660 (+11 jam dari UTC), dan untuk tempat di California di luar penyesuaian waktu musim panas 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() sebagai gantinya. 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 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 dapat berisi waktu dalam sehari dalam format 24 jam jjmm (nilainya berkisar 0000–2359). time akan dilaporkan dalam zona waktu tempat tersebut.
      • close dapat berisi pasangan objek hari dan waktu yang menjelaskan kapan tempat tersebut tutup. Catatan: Jika tempat selalu buka, bagian close akan hilang dari respons. Aplikasi dapat selalu berpatokan pada kondisi selalu-buka yang direpresentasikan sebagai jangka waktu open yang berisi day dengan nilai 0 dan time dengan nilai 0000, dan tanpa close.
    • weekday_text adalah array berisi tujuh string yang menyatakan jam buka yang telah diformat untuk setiap hari dalam seminggu. Jika parameter language telah ditentukan dalam permintaan Place Details, Places Service akan memformat dan melokalkan jam buka secara tepat untuk bahasa tersebut. Urutan elemen dalam array ini bergantung pada parameter language. Beberapa bahasa memulai pekan pada hari Senin, sementara yang lain mulai pada hari Minggu.
  • permanently_closed (tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut tutup permanen atau sementara waktu (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 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: 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: Peringkat tempat ini, dari 0,0 hingga 5,0, berdasarkan gabungan ulasan pengguna.
  • 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 untuk tempat usaha tersebut. Objek pertama dalam array dianggap sebagai aspek utama. Setiap PlaceAspectRating ditentukan sebagai:
      • type nama aspek yang sedang diberi peringkat. 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 mengirim ulasan. Ulasan anonim diatribusikan ke "Pengguna Google". Jika parameter bahasa 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 berisi tag bahasa utama saja, dan bukan tag sekunder yang menunjukkan negara atau wilayah. Misalnya, semua ulasan dalam bahasa Inggris akan diberi tag 'en', dan bukan 'en-AU' atau 'en-UK' dan seterusnya.
    • rating rating pengguna secara keseluruhan untuk tempat ini. Rating ini menggunakan bilangan bulat, berkisar dari 1 hingga 5.
    • text ulasan pengguna. Saat mengulas sebuah lokasi dengan Google Places, ulasan teks dianggap opsional; 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 dimasukkan tanpa pemberitahuan sebelumnya. Lihat daftar jenis yang didukung.
  • url: URL halaman resmi Google untuk tempat ini. Halaman ini adalah halaman milik Google berisi informasi terbaik yang tersedia tentang tempat ini. Aplikasi harus menautkan ke atau menyematkan halaman ini pada setiap layar yang menampilkan hasil detail tentang tempat tersebut kepada pengguna.
  • vicinity: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor gedung, dan lokalitas, tetapi bukan provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilai vicinity berupa 5/48 Pirrama Road, Pyrmont. Properti vicinity hanya ditampilkan untuk Nearby Search.
  • 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 tidak ada rating sama sekali.

Menggunakan komponen Place Overview

Catatan: Contoh ini menggunakan library open source. Lihat README untuk mendapatkan dukungan dan dukungan terkait dengan library.

Coba komponen web. Gunakan Komponen web Ringkasan Tempat untuk mendapatkan detail tempat dengan representasi visual.

Gambar yang menampilkan variasi ukuran x-kecil, kecil, medium, besar, dan x-besar dari Komponen Place Overview ditampilkan berdasarkan kolom ukuran yang dimasukkan oleh pengguna.
Gambar 1: Informasi detail tempat dengan lima variasi ukuran yang berbeda

Merujuk sebuah Tempat dengan ID Tempat

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

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

ID tempat dikecualikan dari pembatasan penyimpanan cache yang disebutkan di Pasal 3.2.3(b) dalam Persyaratan Layanan Google Maps Platform. Oleh karena itu, Anda dapat 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);

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. Jika Anda mengambil informasi tempat menggunakan permintaan Place Details, referensi foto akan ditampilkan untuk materi fotografi yang relevan. Permintaan Nearby Search dan Text Search juga akan menampilkan satu referensi foto per tempat, jika relevan. Dengan layanan Photo, Anda kemudian bisa mengakses foto yang direferensikan dan mengubah ukuran gambar ke ukuran yang 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 akan bervariasi menurut permintaan.

  • Nearby Search atau Text Search 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 Photo akan mengubah ukuran gambar menurut ukuran yang lebih kecil, dengan tetap mempertahankan rasio aspek asli.

Cuplikan kode berikut menerima objek tempat, dan menambahkan penanda ke peta jika ada fotonya. Gambar penanda default digantikan dengan versi kecil dari foto tersebut.

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 dkembalikan oleh layanan Photo berasal dari berbagai lokasi, termasuk foto dari pemilik bisnis dan pengguna. Umumnya, foto ini dapat digunakan tanpa atribusi, atau atribusi yang diperlukan akan disertakan 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.