TMDB APIキーの取得方法とThe Movie Database APIの利用方法

The Movie Database（TMDB）は、映画、テレビ番組、キャスト、アートワークのコミュニティによって構築されたカタログです。そのAPIは、TMDBをクレジットする限り非商用利用は無料であり、そのため無料映画APIのあらゆるリストにおいて通常の出発点となっています。唯一の課題はオンボーディングです。TMDBは2つの異なる認証情報を提供し、公式のはじめにガイドは、どちらを使用すべきか既に知っていることを前提としています。

このガイドでは、アカウント作成、キーのリクエスト、v3キーとv4リードアクセストークンの違い、curlとPythonでの最初の検索と詳細呼び出し、Apidogでテストとして保存された同じ呼び出し、および利用開始初日に遭遇するであろうレート制限、著作権表示ルール、エラーといった、全体的なパスを網羅します。

始める前に必要なもの

• 認証済みのメールアドレスを持つTMDBアカウント。APIは未認証のアカウントを401エラーで拒否します。
• デスクトップブラウザ。TMDBのドキュメントには、API登録ページはモバイルデバイスに最適化されていないと記載されています。
• curl、またはrequestsパッケージを含むPython 3。
• トークンを安全に保存し、リクエストを保持するためのApidog。macOS、Windows、またはLinux用のApidogをダウンロードしてください。

ステップ1：TMDBアカウントを作成する

themoviedb.orgにアクセスし、「Join TMDB」をクリックしてメールアドレスでサインアップします。API設定を触る前に、確認メールを開いて承認してください。これをスキップすると、後で「Email not verified: Your email address has not been verified.」というステータスコード32の、分かりにくい401エラーに遭遇することになります。

ステップ2：APIキーをリクエストする

ログインしたら、アカウント設定を開き、左側のサイドバーにある「API」をクリックします。TMDBのFAQには、これが唯一のルートであると説明されています：「アカウント設定ページの左側のサイドバーにある『API』リンクをクリックすることで、APIキーを申請できます。」

API利用規約に同意した後、簡単なアプリケーションを記入します。何を作成しているのか、URLがある場合はそのURL、データの使用方法の概要、および使用の種類です。個人のプロジェクト、プロトタイプ、および内部ツールには開発者オプションを選択してください。TMDBは、「主要な目的が所有者の利益のために収益を生み出すことである場合」プロジェクトを商用とみなしており、そのパスには彼らの営業チームとの書面による合意が必要です。

送信後、同じ設定ページに2つの認証情報が表示されます。

• APIキー、v3認証用としてラベル付けされています。32文字の16進数文字列です。
• APIリードアクセストークン、はるかに長いJWT形式の文字列です。

TMDBは審査のタイムラインを公開していませんが、実際にはフォームが送信されるとすぐに両方の値が表示されます。他の秘密情報と同様に扱い、コミット、チャットウィンドウ、スクリーンショットに含めないでください。

v3 APIキー vs v4 リードアクセストークン

これら2つの認証情報は「古い」と「新しい」ではありません。これらは同じアプリケーションを識別する2つの方法であり、公式の認証ドキュメントでは、両方が「同じレベルのアクセスを提供する」と述べられています。

TMDB自身の推奨はBearerトークンです：「デフォルトの認証方法はアクセストークンを使用することであり、」「v3とv4の両方のメソッドで利用できる単一の認証プロセスであるという追加の利点があります。」

クライアントがヘッダーを設定できない場合を除き、Bearerヘッダーを使用してください。認証情報をURLから除外することは、APIキーとBearerトークンの決定における一般的な議論の裏付けとなります。URLはログに記録され、キャッシュされ、共有されるためです。

もう一つの違いです。この記事のすべては読み取り専用のカタログデータであり、アプリケーションの認証情報のみが必要です。v4 APIは、リスト、お気に入り、評価、ウォッチリストなどのアカウント機能を追加します。TMDBユーザーのためにこれらに書き込むには、追加のハンドシェイクが必要です：/4/auth/request_tokenからのリクエストトークン、ユーザーの承認、そして/4/auth/access_tokenからのユーザーアクセストークンです。映画を検索したり詳細を読み取ったりするのに、これらのどれも必要ありません。

ステップ3：最初のリクエストを行う

すべてのv3呼び出しはhttps://api.themoviedb.org/3に送信されます。2つのエンドポイントがほとんどの最初のプロジェクトをカバーします：タイトルによる検索、そしてIDによる詳細の取得です。

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 YOUR_READ_ACCESS_TOKEN' \
  --header 'accept: application/json'

レスポンスは、`page`、`results`、`total_pages`、`total_results`を含むページオブジェクトです。各結果には`id`、`title`、`release_date`、`overview`、`poster_path`、`genre_ids`、`vote_average`が含まれます。TMDB自身の検索例では、「ファイト・クラブ」の最初のヒットはID 550で、1999年10月15日に公開されています。

v3キーを使った同じ呼び出しは以下のようになります。認証ヘッダーは一切ありません：

curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=YOUR_API_KEY'

Pythonで映画の詳細を取得する

次に、検索から得られたIDを使って完全なレコードを要求します。映画詳細エンドポイントは、runtime、genres、budget、revenue、overviewを返します。そのappend_to_responseパラメータは、クレジットのようなサブリソースを同じ一回の往復で追加でき、1リクエストあたり最大20個まで追加できます。

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"])

最後の行は人々が見落としがちな部分です。poster_pathは単なるパスです。画像基本ガイドが説明するように、機能するURLはhttps://image.tmdb.org/t/p/、次にw500やoriginalのようなサイズ、そしてパスとなります。/3/configurationはすべての有効なサイズをリストしています。

ステップ4：Apidogでリクエストを実行・保存する

生のリクエストが機能するようになったら、それらを失くさない場所に移動しましょう。Apidogでは、数分で保存・共有可能なテストができます。

1. プロジェクトを作成し、「TMDB」という名前の環境を追加します。これには、base_urlをhttps://api.themoviedb.org/3に設定し、tmdb_tokenにリードアクセストークンを保持する2つの変数を含めます。トークンはUIでマスクされ、エクスポートに含まれないようにシークレットとしてマークしてください。環境変数とシークレット変数に関するガイドがオプションをカバーしています。
2. {{base_url}}/search/movieへのGETリクエストをqueryパラメータとともに追加します。認証タブでBearer Tokenを選択し、{{tmdb_token}}と入力します。これを送信し、200 OKとresults配列が返されることを確認します。
3. {{base_url}}/movie/{{movie_id}}への2番目のGETリクエストを追加します。最初のリクエストのポストプロセッサで、results[0].idをmovie_idとして抽出し、2番目の呼び出しが常に最初の呼び出しに続くようにします。
4. 両方をテストシナリオとして保存し、アサーションを追加します：ステータスが200であること、total_resultsが0より大きいこと、および詳細レスポンスのtitleが空でないこと。連携が変更されるたびにこれを実行します。

このデータに対してフロントエンドを構築していますか？検索エンドポイントのモックサーバーをオンにしてください。Apidogはスキーマに一致するレスポンスを生成するため、UIチームはライブトークンやTMDBの制限に対する実際のリクエストなしにポスターグリッドを構築できます。

レート制限と著作権表示ルール

以下はすべてTMDBのドキュメントからの引用です。

レート制限。TMDBのレート制限ページによると、10秒あたり40リクエストという元の制限は2019年12月16日に無効になりました。上限は「不必要な大量スクレイピングを軽減するため」に依然として存在し、「秒間40リクエストの範囲」です。この数値は通知なしに変更される可能性があるため、HTTP 429を受け取った場合は尊重し、バックオフして再試行してください。

費用。FAQより：「当社のAPIは、データの出典元としてTMDBをクレジットし、画像を帰属表示する限り、非商用利用は無料です。」商用プロジェクトはsales@themoviedb.orgに連絡する必要があります。

著作権表示。アプリケーションにTMDBのロゴと、「この製品はTMDB APIを使用していますが、TMDBによって承認または認証されたものではありません。」という注意書きを表示してください。API利用規約では、少し長い文言を使用しており、ロゴは自身のブランドよりも目立たず、決して色を変更したり、引き伸ばしたり、反転させたり、回転させたりしてはならないと規定しています。

キャッシング。利用規約では、TMDBデータを6ヶ月以上キャッシュすることを禁じています。必要なものは保存できますが、更新計画を立ててください。

SLAなし。TMDBはそれを明確に述べています。タイムアウトと再試行を組み込んでください。

キーの管理。両方の認証情報は環境変数またはシークレットマネージャーに保存し、決してソースコードに含めないでください。もしリポジトリに入ってしまった場合は、設定ページから回転させ、履歴全体でAPIキー漏洩チェックを実行してください。

よくあるエラーとその意味

TMDBは、HTTPステータスコードに加えて、status_codeとstatus_messageを含むJSONボディを返します。エラーリファレンスには多数のコードがリストされていますが、これらは最初に見るであろうものです。

よくある質問

TMDB APIキーは無料ですか？

はい、著作権表示を伴う非商用利用は無料です。有料のセルフサービスティアはありません。プロジェクトが収益を得る場合は、TMDBは営業チームを通じて商業契約を締結するよう求めています。

APIキーとリードアクセストークンのどちらを使うべきですか？

Bearerヘッダーとしてリードアクセストークンを使用してください。TMDBはこれをデフォルトと呼び、v3とv4の両方で機能し、URLから外れます。v3キーは、クエリパラメータしか送信できないツール向けに存在します。この概念が新しい場合は、APIキーとは何かという入門書がTMDBが採用しているモデルを説明しています。

ブラウザやモバイルアプリから直接TMDBを呼び出すことはできますか？

可能です。しかし、クライアントに配布されるものは何でも公開され、トークンも含まれます。個人的なプロジェクトの場合、これは許容されるリスクです。ユーザーがいるものについては、TMDBの前に小さなバックエンドまたはサーバーレス関数を置き、トークンをそこに保持し、人気のあるクエリをキャッシュしてください。

v3とv4の違いは何ですか？

v3はカタログです：検索、映画・テレビの詳細、人物、画像、発見。v4はリスト、お気に入り、評価、ウォッチリストなどのアカウント機能をカバーし、その書き込みエンドポイントにはユーザーアクセストークンが必要です。あなたのリードアクセストークンは両方に対して認証されます。

次に進むべき場所

これで、機能するTMDB APIキー、どの認証情報を送信すべきかというルール、curlとPythonでの検索から詳細へのフロー、そしてApidogテストシナリオとして保存された同じフローを手に入れました。次に、フィルタリングされたブラウジングのためにdiscover/movieを追加し、共有する前にアプリに帰属表示の通知を記載してください。カタログの他のすべては、同じベースURL、Bearerヘッダー、エラー形式を使用します。