Maps JavaScript API: Mendapatkan Kunci API atau Client ID

Catatan: Premium Plan Google Maps Platform tidak lagi tersedia untuk pendaftar atau pelanggan baru.

Memilih metode autentikasi

Untuk menggunakan Maps JavaScript API:

  • Pelanggan dengan Premium Plan dapat menggunakan kunci API atau client ID untuk mengautentikasi permintaan.
  • Pelanggan dengan lisensi sebelumnya harus menggunakan client ID untuk mengautentikasi permintaan.

Alat dan laporan yang tersedia di setiap metode autentikasi dirangkum di sini:

  • Autentikasi menggunakan kunci API (Premium Plan)
    Dengan menggunakan kunci API untuk mengautentikasi permintaan, Anda dapat:
    • Mengelola semua API Anda di halaman API pada Google Cloud Console.
    • Mengakses data penggunaan real-time dan data penggunaan historis 30 hari di Cloud Console.
    • Menambahkan parameter channel ke permintaan sehingga Anda dapat melihat laporan penggunaan yang lebih detail.
    • Melihat laporan penggunaan berisi data lebih dari 30 hari di Cloud Console.
  • Autentikasi menggunakan Client ID (Premium Plan atau lisensi sebelumnya)
    Dengan menggunakan client ID untuk mengautentikasi permintaan, Anda dapat:
    • Menambahkan parameter channel ke permintaan sehingga Anda dapat melihat laporan penggunaan yang lebih detail.
    • Melihat laporan penggunaan berisi data lebih dari 30 hari di Cloud Console.
    • Menggunakan alat Maps Analytics untuk Maps JavaScript API.

Dapatkan informasi selengkapnya tentang laporan yang tersedia untuk pelanggan Premium Plan.

Autentikasi menggunakan kunci API

Membuat kunci API

Kunci API adalah ID unik yang mengautentikasi permintaan terkait project untuk tujuan penggunaan dan penagihan. Anda harus memiliki setidaknya satu kunci API terkait project.

Untuk membuat kunci API:

  1. Di Cloud Console, pada halaman pemilih project, pilih atau buat project Google Cloud yang ingin Anda tambahkan kunci API.

    Buka halaman pemilih project

    Catatan: Untuk mendapatkan akses penuh ke fitur yang terdapat dalam paketnya, pelanggan Premium harus menggunakan project yang terkait dengan akun Premium mereka. Saat membeli lisensi, Anda menerima nama aset Premium Anda dalam format berikut: gme-[company] > proj-[number] ([type]). Untuk memastikan Anda mengakses project yang benar, login ke konsol sebagai pemilik project menggunakan console.cloud.google.com/project/number (ganti number dengan nomor project Anda). Anda dapat menemukan pemilik project di email selamat datang.

  2. Buka halaman Google Maps Platform > Kredensial.

    Buka halaman Kredensial

  3. Pada halaman Kredensial, klik Buat kredensial > Kunci API.
    Dialog Kunci API dibuat akan menampilkan kunci API yang baru dibuat.
  4. Klik Tutup.
    Kunci API baru dicantumkan pada halaman Kredensial di bagian Kunci API.
    (Jangan lupa untuk membatasi kunci API sebelum menggunakannya dalam produksi.)

Menambahkan kunci API ke aplikasi

Anda harus menyertakan kunci API pada setiap permintaan Google Maps Platform. Pada contoh berikut, ganti YOUR_API_KEY dengan kunci API Anda.

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
type="text/javascript"></script>

HTTPS diperlukan untuk permintaan yang menggunakan kunci API, dan direkomendasikan untuk permintaan yang menggunakan client ID. HTTPS juga diperlukan untuk aplikasi yang menyertakan data pengguna sensitif - seperti lokasi pengguna - dalam permintaan.

Membatasi kunci API

Membatasi kunci API akan meningkatkan keamanan aplikasi Anda dengan memastikan hanya permintaan sah yang dibuat dengan kunci API Anda. Sebaiknya Anda mengikuti petunjuk untuk menetapkan pembatasan pada kunci API Anda. Untuk informasi selengkapnya, lihat Praktik terbaik keamanan API.

Cara membatasi kunci API:

  1. Buka halaman Google Maps Platform > Kredensial.

    Buka halaman Kredensial

  2. Pilih kunci API yang ingin Anda batasi. Halaman properti kunci API akan muncul.
  3. Di bagian Pembatasan kunci, tetapkan pembatasan berikut:
    • Pembatasan aplikasi:
      1. Untuk menerima permintaan dari daftar situs yang Anda berikan, pilih Perujuk HTTP (situs) dari daftar Pembatasan aplikasi.
      2. Tentukan satu atau beberapa situs web perujuk. Misalnya, *.google.com menerima semua situs yang diakhiri dengan google.com, seperti https://developers.google.com.

        Catatan: Perujuk file:// memerlukan representasi khusus untuk ditambahkan ke pembatasan kunci. Bagian "file://" harus diganti dengan "__file_url__" sebelum ditambahkan ke pembatasan kunci. Misalnya, "file:///path/to/" harus diformat sebagai "__file_url__//path/to/*". Setelah mengaktifkan perujuk file://, sebaiknya periksa penggunaan Anda secara teratur untuk memastikan kecocokannya dengan ekspektasi Anda.

    • Pembatasan API:
      1. Klik Batasi kunci.
      2. Pilih Google Maps Platform dari dropdown Pilih API. (Jika Google Maps Platform tidak tercantum, Anda perlu mengaktifkannya.
      3. Jika project Anda menggunakan Places Library, pilih juga Places API. Demikian juga jika project Anda menggunakan layanan lain di JavaScript API (Layanan Directions, Layanan Distance Matrix, Layanan Elevation, dan/atau Layanan Geocoding), Anda juga harus mengaktifkan dan memilih API yang sesuai dalam daftar ini.
  4. Untuk menyelesaikan perubahan, klik Simpan.

Autentikasi menggunakan client ID

Setelah membeli lisensi Premium Plan Google Maps Platform, Anda akan menerima email selamat datang dari Google yang berisi client ID, yang mengizinkan akses ke berbagai laporan dan alat Premium Plan Google Maps Platform.

Semua client ID diawali dengan gme-. Berikut adalah format dari client ID standar.

gme-[company] > proj-[number] ([type])

Anda dapat mengautentikasi permintaan dengan Maps JavaScript API menggunakan client ID bersama pendaftaran URL (bukan kunci API).

Catatan: Client ID ini bukan kunci, dan hanya dapat digunakan oleh URL yang Anda beri otorisasi. Baca cara mendaftarkan URL yang diotorisasi selengkapnya.

Menetapkan client ID saat memuat API

Kode di bawah ini menunjukkan cara mengganti YOUR_CLIENT_ID dengan client ID Anda sendiri saat memuat Maps JavaScript API.

  <script async defer
  src="https://maps.googleapis.com/maps/api/js?client=YOUR_CLIENT_ID&v=quarterly&callback=initMap"></script>

Anda harus menentukan versi rilis (juga disebut sebagai versi fitur-stabil) atau versi terdahulu, dengan menambahkan parameter v=quarterly. Aplikasi yang menggunakan versi eksperimental tidak tercakup dalam SLA Premium Plan Google Maps Platform.

Catatan: Jika sebelumnya Anda menggunakan kunci API untuk autentikasi dan beralih untuk menggunakan client ID, Anda harus menghapus parameter key sebelum memuat API. API akan gagal dimuat jika client ID dan kunci API disertakan bersamaan.

Mendaftarkan URL yang diberi otorisasi

Untuk mencegah pihak ketiga menggunakan client ID Anda di situs mereka sendiri, penggunaan client ID Anda dibatasi pada daftar URL yang secara spesifik Anda beri otorisasi.

Untuk melihat URL yang sudah Anda beri otorisasi atau untuk memberi otorisasi URL tambahan:

  1. Login ke Google Cloud Console.
  2. Di menu sebelah kiri, klik Maps: Kelola Client ID.

Anda dapat menambahkan hingga 100 URL sekaligus. Sebuah Client ID dapat dikaitkan dengan maksimal 3.000 URL yang diberi otorisasi. Jika Anda memperkirakan aplikasi Anda akan menghosting konten Google Maps yang memuat lebih dari 3.000 lokasi, sebaiknya Anda beralih menggunakan kunci API.

Pertimbangan berikut berlaku sehubungan dengan URL yang diberi otorisasi:

Nama domain atau alamat IP tidak wajib harus bisa diakses oleh umum.
Misalnya, http://myintranet dan http://192.168.1.1 adalah entri yang valid.
Semua subdomain dari domain yang telah diberi otorisasi juga ikut mendapat otorisasi.
Misalnya, jika http://example.com diberi otorisasi, berarti http://www.example.com juga ikut mendapat otorisasi. Hal sebaliknya tidak berlaku: jika http://www.example.com diberi otorisasi, http://example.com belum tentu ikut mendapat otorisasi.
Semua subjalur dari jalur yang telah diberi otorisasi juga ikut mendapat otorisasi.
Misalnya, jika http://example.com diberi otorisasi, berarti http://example.com/foo juga ikut mendapat otorisasi. Selain itu, karena subdomain dari domain yang telah diberi otorisasi juga ikut mendapat otorisasi, berarti http://sub.example.com/bar juga turut mendapat otorisasi.
Jalur membedakan huruf besar dan kecil.
Misalnya, http://www.example.com/ThisPath/ tidak sama dengan http://www.example.com/thispath/.
Anda dapat membatasi URL yang valid pada URL yang menggunakan port tertentu.
Misalnya, jika http://example.com:8080/foo diberi otorisasi, tidak berarti http://example.com juga ikut mendapat otorisasi.
Protokol HTTP dan HTTPS dianggap URL yang berbeda.
Misalnya, jika https://example.com diberi otorisasi, http://example.com belum tentu ikut mendapat otorisasi.

Semua aturan di atas berlaku pada setiap otorisasi, jadi Anda harus berhati-hati merencanakan otorisasi. Misalnya, karena semua subjalur dari jalur yang telah diberi otorisasi juga ikut mendapat otorisasi, serta semua subdomain, Anda mungkin berujung memberi otorisasi untuk halaman yang sebenarnya tidak Anda inginkan. Contoh:

http://example.com/ juga memberi otorisasi http://sub.example.com/path.

Untuk informasi selengkapnya, lihat Pemecahan Masalah Otorisasi URL Premium Plan Google Maps Platform.