The Movie Database (TMDB) adalah katalog film, acara TV, pemeran, dan karya seni yang dibangun oleh komunitas. API-nya gratis untuk penggunaan non-komersial selama Anda memberikan kredit kepada TMDB, yang menjadikannya titik awal biasa di daftar mana pun dari API film gratis. Tantangannya adalah orientasi: TMDB memberikan Anda dua kredensial berbeda, dan panduan memulai resmi mengasumsikan Anda sudah tahu mana yang harus digunakan.
Panduan ini mencakup seluruh jalur: akun, permintaan kunci, kunci v3 versus token akses baca v4, panggilan pencarian dan detail pertama di curl dan Python, panggilan yang sama disimpan sebagai pengujian di Apidog, serta batas laju, aturan atribusi, dan kesalahan yang akan Anda temui pada hari pertama.
Apa yang Anda Butuhkan Sebelum Memulai
- Akun TMDB dengan alamat email yang terverifikasi. API menolak akun yang tidak terverifikasi dengan kode 401.
- Browser desktop. Dokumen TMDB menyatakan bahwa halaman pendaftaran API tidak dioptimalkan untuk perangkat seluler.
- curl, atau Python 3 dengan paket
requests. - Apidog, untuk menyimpan token dengan aman dan menjaga permintaan. Unduh Apidog untuk macOS, Windows, atau Linux.
Langkah 1: Buat Akun TMDB
Buka themoviedb.org, klik “Join TMDB,” dan daftar dengan alamat email. Buka email verifikasi dan konfirmasikan sebelum Anda menyentuh pengaturan API. Lewati ini dan Anda akan menemukan 401 yang membingungkan nanti, kode status 32: “Email not verified: Your email address has not been verified.”
Langkah 2: Minta Kunci API
Setelah Anda masuk, buka pengaturan akun Anda dan klik “API” di bilah sisi kiri. FAQ TMDB menjelaskan ini sebagai satu-satunya rute: “You can apply for an API key by clicking the ‘API’ link from the left hand sidebar within your account settings page.”
Anda akan menyetujui persyaratan penggunaan API, lalu mengisi formulir singkat: apa yang Anda bangun, URL jika Anda memilikinya, ringkasan bagaimana Anda akan menggunakan data, dan jenis penggunaan. Pilih opsi pengembang untuk proyek pribadi, prototipe, dan alat internal. TMDB menganggap proyek bersifat komersial “jika tujuan utamanya adalah menghasilkan pendapatan untuk keuntungan pemilik,” dan jalur itu memerlukan perjanjian tertulis dengan tim penjualan mereka.
Setelah Anda mengirimkan, halaman pengaturan yang sama menampilkan dua kredensial:
- Kunci API, dilabeli untuk otentikasi v3. Sebuah string heksadesimal 32 karakter.
- Token Akses Baca API, sebuah string gaya JWT yang jauh lebih panjang.
TMDB tidak mempublikasikan jadwal peninjauan; pada praktiknya kedua nilai muncul segera setelah formulir diproses. Perlakukan mereka seperti rahasia lainnya dan jauhkan dari commit, jendela obrolan, dan tangkapan layar.
Kunci API v3 vs Token Akses Baca v4
Kedua kredensial ini bukan "lama" dan "baru". Mereka adalah dua cara mengidentifikasi aplikasi yang sama, dan dokumen otentikasi resmi menyatakan bahwa keduanya "memberikan tingkat akses yang sama."
| Kunci API (v3) | Token Akses Baca API | |
|---|---|---|
| Cara Anda mengirimkannya | Parameter kueri: ?api_key=KUNCI_ANDA |
Header: Authorization: Bearer TOKEN_ANDA |
| Bekerja dengan | Endpoint v3 di bawah /3/ |
Endpoint v3 dan v4 |
| Default TMDB | Tidak | Ya |
| Muncul di log server dan riwayat browser | Ya, ada di URL | Tidak |
Rekomendasi TMDB sendiri adalah token Bearer: “Metode default untuk otentikasi adalah dengan token akses Anda,” dan “memiliki manfaat tambahan yaitu proses otentikasi tunggal yang dapat Anda gunakan di metode v3 dan v4.”
Gunakan header Bearer kecuali klien Anda tidak dapat mengatur header. Menjaga kredensial keluar dari URL adalah argumen yang sama di balik keputusan kunci API versus token bearer: URL dicatat, di-cache, dan dibagikan.
Satu lagi perbedaan. Semua yang ada dalam artikel ini adalah data katalog hanya-baca, yang hanya memerlukan kredensial aplikasi. API v4 menambahkan fitur akun seperti daftar, favorit, peringkat, dan daftar tontonan. Menulis ke fitur tersebut untuk pengguna TMDB membutuhkan jabat tangan ekstra: token permintaan dari /4/auth/request_token, persetujuan pengguna, lalu token akses pengguna dari /4/auth/access_token. Tidak ada yang dibutuhkan untuk mencari film atau membaca detail.
Langkah 3: Buat Permintaan Pertama Anda
Semua panggilan v3 mengarah ke https://api.themoviedb.org/3. Dua endpoint mencakup sebagian besar proyek pertama: cari berdasarkan judul, lalu ambil detail berdasarkan ID.
Cari Film dengan curl
curl --request GET \
--url 'https://api.themoviedb.org/3/search/movie?query=fight%20club&include_adult=false&language=en-US&page=1' \
--header 'Authorization: Bearer TOKEN_AKSES_BACA_ANDA' \
--header 'accept: application/json'
Responsnya adalah objek halaman dengan page, results, total_pages, dan total_results. Setiap hasil membawa id, title, release_date, overview, poster_path, genre_ids, dan vote_average. Dalam contoh pencarian TMDB sendiri, hasil pertama untuk “fight club” adalah id 550, dirilis 1999-10-15.
Panggilan yang sama dengan kunci v3 terlihat seperti ini. Perhatikan tidak ada header otentikasi sama sekali:
curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=KUNCI_API_ANDA'
Dapatkan Detail Film dengan Python
Sekarang ambil ID dari pencarian dan minta catatan lengkapnya. Endpoint detail film mengembalikan runtime, genres, budget, revenue, dan overview. Parameter append_to_response-nya menambahkan sub-sumber daya seperti kredit ke perjalanan pulang-pergi yang sama, hingga 20 per permintaan.
import os
import requests
TOKEN = os.environ["TMDB_READ_ACCESS_TOKEN"]
BASE = "https://api.themoviedb.org/3"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "accept": "application/json"}
def search_movie(title):
r = requests.get(
f"{BASE}/search/movie",
params={"query": title, "include_adult": "false", "language": "en-US"},
headers=HEADERS,
timeout=10,
)
r.raise_for_status()
return r.json()["results"]
def movie_details(movie_id):
r = requests.get(
f"{BASE}/movie/{movie_id}",
params={"append_to_response": "credits"},
headers=HEADERS,
timeout=10,
)
r.raise_for_status()
return r.json()
hit = search_movie("Fight Club")[0]
movie = movie_details(hit["id"])
print(movie["title"], movie["release_date"], f'{movie["runtime"]} min')
print("https://image.tmdb.org/t/p/w500" + movie["poster_path"])
Baris terakhir adalah bagian yang sering orang lewatkan. poster_path hanyalah sebuah jalur. Seperti yang dijelaskan oleh panduan dasar gambar, URL yang berfungsi adalah https://image.tmdb.org/t/p/, lalu ukuran seperti w500 atau original, lalu jalur tersebut. /3/configuration mencantumkan setiap ukuran yang valid.
Langkah 4: Jalankan dan Simpan Permintaan di Apidog
Setelah panggilan mentah berfungsi, pindahkan ke tempat Anda tidak akan kehilangannya. Di Apidog ini membutuhkan beberapa menit dan meninggalkan Anda dengan pengujian yang tersimpan dan dapat dibagikan.
- Buat proyek dan tambahkan lingkungan bernama “TMDB” dengan dua variabel:
base_urldiatur kehttps://api.themoviedb.org/3, dantmdb_tokenmenyimpan token akses baca Anda. Tandai token sebagai rahasia agar disembunyikan di UI dan tidak disertakan dalam ekspor; panduan untuk variabel lingkungan dan rahasia mencakup opsi-opsi tersebut. - Tambahkan permintaan GET ke
{{base_url}}/search/moviedengan parameterquery. Pada tab Auth, pilih Bearer Token dan masukkan{{tmdb_token}}. Kirim dan konfirmasikan bahwa Anda mendapatkan 200 dan arrayresults. - Tambahkan permintaan GET kedua ke
{{base_url}}/movie/{{movie_id}}. Di post-processor permintaan pertama, ekstrakresults[0].idke dalammovie_idagar panggilan kedua selalu mengikuti yang pertama. - Simpan keduanya sebagai skenario pengujian dengan pernyataan: status sama dengan 200,
total_resultslebih besar dari 0, dantitledalam respons detail tidak kosong. Jalankan kapan pun integrasi berubah.
Membangun antarmuka pengguna (frontend) berdasarkan data ini? Aktifkan server tiruan untuk endpoint pencarian. Apidog menghasilkan respons yang sesuai dengan skema, sehingga tim UI dapat membangun kisi poster tanpa token langsung atau permintaan nyata terhadap batasan TMDB.
Batas Laju dan Aturan Atribusi
Semua yang ada di bawah ini dikutip dari dokumen TMDB.
Batas Laju. Halaman pembatasan laju TMDB menyatakan bahwa batas asli 40 permintaan setiap 10 detik dinonaktifkan pada 16 Desember 2019. Batas atas tetap ada “untuk membantu mengurangi scraping massal yang tidak perlu,” dan mereka “berada di kisaran 40 permintaan per detik.” Angka tersebut dapat berubah tanpa pemberitahuan, jadi patuhi setiap HTTP 429, jeda, dan coba lagi.
Biaya. Dari FAQ: “API kami bebas digunakan untuk tujuan non-komersial selama Anda mengatribusikan TMDB sebagai sumber data dan/atau gambar.” Proyek komersial harus menghubungi sales@themoviedb.org.
Atribusi. Tampilkan logo TMDB dan pemberitahuan ini di aplikasi Anda: “Produk ini menggunakan API TMDB tetapi tidak didukung atau disertifikasi oleh TMDB.” Ketentuan penggunaan API menggunakan kata-kata yang sedikit lebih panjang dan mengharuskan logo kurang menonjol daripada merek Anda sendiri, dan tidak pernah diubah warna, diregangkan, dibalik, atau diputar.
Caching. Ketentuan melarang caching data TMDB lebih dari enam bulan. Simpan apa yang Anda butuhkan, tetapi rencanakan penyegaran.
Tanpa SLA. TMDB mengatakannya dengan jelas. Bangun batas waktu dan coba lagi.
Kebersihan Kunci. Kedua kredensial harus berada dalam variabel lingkungan atau manajer rahasia, tidak pernah dalam sumber. Jika salah satu mendarat di repo, putar dari halaman pengaturan dan jalankan pemeriksaan kebocoran kunci API di seluruh riwayat Anda.
Kesalahan Umum dan Artinya
TMDB mengembalikan body JSON dengan status_code dan status_message bersama status HTTP. Referensi kesalahan mencantumkan lusinan kode; ini adalah yang akan Anda lihat pertama kali.
| HTTP | status_code | Pesan | Penyebab dan Perbaikan Umum |
|---|---|---|---|
| 401 | 7 | Kunci API tidak valid: Anda harus diberikan kunci yang valid. | Kredensial salah atau slot salah. Kunci v3 masuk ke api_key, token akses baca masuk ke header Bearer, tidak pernah sebaliknya. Periksa adanya spasi di akhir. |
| 401 | 3 | Otentikasi gagal: Anda tidak memiliki izin untuk mengakses layanan. | Kredensial salah format atau header hilang. Konfirmasi bahwa itu berbunyi Authorization: Bearer <token> dengan satu spasi. |
| 401 | 32 | Email tidak diverifikasi: Alamat email Anda belum diverifikasi. | Verifikasi email TMDB Anda, lalu coba lagi. Tidak perlu kunci baru. |
| 404 | 34 | Sumber daya yang Anda minta tidak dapat ditemukan. | ID salah atau salah ketik di jalur. Itu /3/movie/550, bukan /3/movies/550. |
| 429 | 25 | Jumlah permintaan Anda (#) melebihi batas yang diizinkan (40). | Melebihi batas burst. Tunggu sebentar dan coba lagi dengan backoff; lakukan pencarian batch dengan append_to_response. |
FAQ
Apakah Kunci API TMDB Gratis?
Ya, untuk penggunaan non-komersial dengan atribusi. Tidak ada tingkat layanan mandiri berbayar. Jika proyek Anda menghasilkan pendapatan, TMDB meminta Anda untuk mengatur perjanjian komersial melalui tim penjualannya.
Haruskah saya menggunakan kunci API atau token akses baca?
Gunakan token akses baca sebagai header Bearer. TMDB menyebutnya sebagai default, berfungsi di v3 dan v4, dan tidak masuk ke URL Anda. Kunci v3 ada untuk alat yang hanya dapat mengirim parameter kueri. Jika konsep ini baru, pengantar tentang apa itu kunci API menjelaskan model yang diikuti TMDB.
Bisakah saya memanggil TMDB langsung dari browser atau aplikasi seluler?
Bisa, tetapi apa pun yang dikirimkan ke klien bersifat publik, termasuk token Anda. Untuk proyek pribadi, itu adalah risiko yang diterima. Untuk apa pun yang melibatkan pengguna, tempatkan fungsi backend kecil atau tanpa server di depan TMDB, simpan token di sana, dan cache kueri populer.
Apa Perbedaan antara v3 dan v4?
v3 adalah katalog: pencarian, detail film dan TV, orang, gambar, penemuan. v4 mencakup fitur akun seperti daftar, favorit, peringkat, dan daftar tontonan, dan endpoint tulisnya memerlukan token akses pengguna. Token akses baca Anda mengautentikasi terhadap keduanya.
Ke Mana Selanjutnya
Anda sekarang memiliki kunci API TMDB yang berfungsi, aturan untuk kredensial mana yang akan dikirim, alur pencarian-lalu-detail di curl dan Python, dan alur yang sama yang disimpan sebagai skenario pengujian Apidog. Selanjutnya, tambahkan discover/movie untuk penjelajahan yang difilter dan letakkan pemberitahuan atribusi di aplikasi Anda sebelum Anda membagikannya. Semua yang lain di katalog menggunakan URL dasar yang sama, header Bearer, dan bentuk kesalahan.