Menggunakan token sesi dengan Map Tiles API

Token sesi adalah bagian data (UUID) yang digunakan dalam panggilan REST untuk mengidentifikasi sesi—serangkaian pertukaran pesan terkait. Anda harus menyertakan token sesi dalam semua permintaan untuk Kartu 2D dan gambar Street View. Anda menyertakannya sebagai nilai parameter session yang ditambahkan ke semua URL permintaan.

Di Map Tiles API, token sesi mewakili kumpulan opsi tampilan yang ditentukan. Artinya, Anda tidak perlu meneruskan serangkaian opsi tampilan dengan setiap permintaan kartu. Anda dapat menggunakan token sesi yang sama di beberapa klien. Token sesi saat ini berlaku selama dua minggu sejak waktu penerbitannya, tetapi hal ini dapat berubah. Anda dapat memeriksa waktu habis masa berlaku token sesi kapan saja dengan melihat kolom expiry dalam pesan respons.

Permintaan token sesi

Untuk meminta token sesi, kirim permintaan POST HTTPS ke endpoint createSession, seperti yang ditunjukkan pada contoh berikut. Anda harus mengirim permintaan dengan header Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

Kolom wajib diisi

mapType

Tipe peta dasar. Nilai ini dapat berupa salah satu dari berikut:

roadmap
Petak peta yang digambar Google Maps standar.
satellite
Citra satelit.
terrain
Citra medan. Saat memilih terrain sebagai jenis peta, Anda juga harus menyertakan jenis lapisan layerRoadmap (dijelaskan di bagian Kolom opsional).
streetview
Panorama Street View. Untuk mengetahui informasi selengkapnya, lihat Kartu Street View.
language

Tag bahasa IETF yang menentukan bahasa yang digunakan untuk menampilkan informasi pada kartu. Misalnya, en-US menentukan bahasa Inggris seperti yang digunakan di Amerika Serikat.

region

ID region Common Locale Data Repository (dua huruf besar) yang mewakili lokasi fisik pengguna. Misalnya, US.

Kolom opsional

imageFormat
Menentukan format file yang akan ditampilkan. Nilai yang valid adalah jpeg atau png. File JPEG tidak mendukung transparansi, sehingga tidak direkomendasikan untuk kartu overlay. Jika Anda tidak menentukan imageFormat, format terbaik untuk kartu akan dipilih secara otomatis.
scale

Memperbesar ukuran elemen peta (seperti label jalan), sekaligus mempertahankan ukuran ubin dan area cakupan ubin default. Meningkatkan skala juga akan mengurangi jumlah label pada peta, sehingga mengurangi kekacauan. Nilai berikut adalah nilai scale yang valid:

  • scaleFactor1x: Default.
  • scaleFactor2x: Melipatgandakan ukuran label dan menghapus label fitur minor.
  • scaleFactor4x: Mengempatkan ukuran label dan menghapus label fitur minor.

Contoh berikut menunjukkan efek penskalaan elemen peta.

Faktor Skala 1x Faktor Skala 2x
Peta yang menampilkan faktor skala 1x Peta yang menampilkan faktor skala 2x
highDpi
Menentukan apakah akan menampilkan ubin beresolusi tinggi. Jika faktor skala ditingkatkan, highDpi akan digunakan untuk meningkatkan ukuran kartu. Biasanya, peningkatan faktor skala akan memperbesar ubin yang dihasilkan menjadi gambar dengan ukuran yang sama, yang menurunkan kualitas. Dengan highDpi, ukuran yang dihasilkan juga ditingkatkan, sehingga kualitasnya tetap terjaga. DPI adalah singkatan dari Dots per Inch, dan DPI Tinggi berarti kartu dirender menggunakan lebih banyak titik per inci daripada biasanya. Jika true, jumlah piksel di setiap dimensi x dan y akan dikalikan dengan faktor skala (yaitu 2x atau 4x). Area cakupan kartu tidak berubah. Parameter ini hanya berfungsi dengan nilai scale 2x atau 4x. Tindakan ini tidak berpengaruh pada kartu skala 1x.
Faktor Skala 1x Faktor Penskalaan 2x DPI Tinggi
Peta ditampilkan pada resolusi reguler Peta ditampilkan pada resolusi DPI Tinggi 2x
layerTypes

Array nilai yang menentukan jenis lapisan yang ditambahkan ke peta. Nilai yang valid adalah:

layerRoadmap
Wajib jika Anda menentukan terrain sebagai jenis peta. Secara opsional, juga dapat ditumpangkan pada jenis peta satellite. Tidak memengaruhi kartu roadmap.
layerStreetview
Menampilkan jalan dan lokasi yang dilengkapi Street View menggunakan garis batas biru di peta.
layerTraffic
Menampilkan kondisi lalu lintas saat ini.
styles

Array objek gaya JSON yang menentukan tampilan dan tingkat detail fitur peta seperti jalan, taman, dan area pemukiman. Gaya visual digunakan untuk menyesuaikan peta dasar Google standar. Parameter styles hanya valid jika jenis peta adalah roadmap. Untuk mengetahui sintaksis gaya lengkapnya, lihat Referensi Gaya.

overlay

Nilai boolean yang menentukan apakah layerTypes harus dirender sebagai overlay terpisah, atau digabungkan dengan gambar dasar. Jika true, peta dasar tidak akan ditampilkan. Jika Anda belum menentukan layerTypes, nilai ini akan diabaikan.

Misalnya, meminta jenis peta satellite dengan lapisan layerRoadmap, dan overlay ditetapkan ke false akan menghasilkan ubin yang setara dengan jenis peta hybrid yang digunakan di Maps JavaScript API (gambar kiri). Jenis peta dan lapisan yang sama dengan overlay yang ditetapkan ke true akan menghasilkan ubin transparan dengan overlay peta, yang ditata dengan tepat untuk ditempatkan di atas citra satelit (gambar kanan).

overlay: salah overlay: true
Overlay ditetapkan ke salah Overlay disetel ke true

JSON berikut adalah contoh isi permintaan standar yang berisi kolom wajib dan opsional.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

Contoh ini memberikan overlay yang cocok untuk digabungkan dengan citra satelit. Contoh ini berisi overlay peta dan tampilan jalan. Peta yang dihasilkan akan dirender dengan nama dan data dalam bahasa Inggris, seperti yang digunakan di Amerika Serikat.

apiOptions: Array nilai yang menentukan opsi tambahan yang akan diterapkan. Opsi yang didukung adalah:

  • MCYJ5E517XR2JC - Ikut serta dalam gaya peta baru. Selama periode keikutsertaan, permintaan Anda akan mendapatkan gaya yang ada kecuali jika nilai ini ditentukan.

Respons token sesi

JSON berikut adalah contoh isi respons.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

Daftar berikut berisi definisi kolom dalam isi respons.

session
Nilai token sesi yang harus Anda sertakan dalam semua permintaan Map Tiles API.
expiry
String yang berisi waktu (dalam detik sejak epoch) saat token berakhir masa berlakunya. Token sesi berlaku selama dua minggu sejak waktu pembuatannya, tetapi kebijakan ini dapat berubah tanpa pemberitahuan.
tileWidth
Lebar kartu yang diukur dalam piksel.
tileHeight
Tinggi kartu yang diukur dalam piksel.
imageFormat
Format gambar, yang dapat berupa png atau jpeg.