NHK番組表API（5さい）

NHK番組表APIはその名の通り、NHKの番組情報を取得できるWeb APIです。公開からほぼ5年がたっていますが意外と知られていない気がするので、改めて勝手に紹介させていただくとともに（私はNHKの職員ではありません）、個人的な希望を追記します。

このAPIでは、地上波のNHK総合、Eテレだけでなく、BSやラジオ、ネットラジオ、ワンセグまで、NHKが放送するあらゆる番組の情報を取得できます（ただし12/1に始まったばかりのBS4K/8K放送にはまだ対応していないようです）。利用規約に同意すれば、誰でも無償で利用することができます。

API利用者用の公式ポータルサイトが用意されており、ここで次のような機能が提供されています：

- 利用申し込み（ユーザー登録、アプリ登録、APIキー発行）
- API仕様、[利用規約](https://api-portal.nhk.or.jp/ja/UsePolicy)、[FAQ](https://api-portal.nhk.or.jp/ja/faq-page)などの参照
- 実際にAPIの動作を見る
- [APIステータス](https://api-portal.nhk.or.jp/ja/api_status)の確認

この記事で説明していない、仕様の詳細などについてはこちらの公式ポータルサイトを参照してください。

**＜NHK番組表APIポータルサイト＞**
https://api-portal.nhk.or.jp
<img width="1089" alt="NHK_api_portal.png" src="https://qiita-image-store.s3.amazonaws.com/0/59211/5d8afd18-4d2a-adcf-f307-a3cfae848073.png">

#機能の概要

次の4つのAPIが用意されています。

1. Program List API
地域、サービス（EテレとかBS1とかFMとか）、日付を指定して番組リストを取得します。

2. Program Genre API
地域、ジャンル、日付を指定して番組リストを取得します。
※ジャンルの指定にはARIB STD-B10という放送規格で定められた定数を指定するのですが、~~この規格は現在無償では入手できないようですし~~、ちょっとこのAPIは放送業界の方でないと使いこなすのは難しいかも。。ちなみに例えば「チコちゃんに叱られる」だとジャンルは"0515"（バラエティ/その他）となります。
※12/5追記：ARIB STD-B10は[こちら](https://www.arib.or.jp/kikaku/kikaku_hoso/std-b10.html)から入手できます。英語版なら無償ダウンロードも可能でした。

3. Program Info API
番組IDを指定することで、該当する番組の詳細情報を取得します。

4. Now On Air API
地域、サービスを指定して、現在放送中のものと、その直前直後の番組情報を取得します。

いずれのAPIでも番組情報はJSON形式で返されます。個々の番組について取得できる情報には、番組IDや放送時間に加えて、以下の項目が含まれます。出演者、ロゴ画像あたりがちょっと楽しげですね♪

- 番組名
- 番組内容
- 番組詳細
- 出演者
- ジャンル
- 番組ロゴ画像*
- 番組サイトURL*
- ハッシュタグ*

*: Program Info APIでのみ取得可能

例）12/1放送の「チコちゃんに叱られる」の番組情報をProgram Info APIで取得すると次のようになります（レスポンスの後半に注目）：

```
$ curl -s "http://api.nhk.or.jp/v2/pg/info/130/g1/2018120108256.json?key=<APIキー>" | jq .
{
  "list": {
    "g1": [
      {
        "id": "2018120108256",
        "event_id": "08256",
        "start_time": "2018-12-01T08:15:00+09:00",
        "end_time": "2018-12-01T09:00:00+09:00",
        "area": {
          "id": "130",
          "name": "東京"
        },
        "service": {
          "id": "g1",
          "name": "ＮＨＫ総合１",
          "logo_s": {
            "url": "//www.nhk.or.jp/common/img/media/gtv-100x50.png",
            "width": "100",
            "height": "50"
          },
          "logo_m": {
            "url": "//www.nhk.or.jp/common/img/media/gtv-200x100.png",
            "width": "200",
            "height": "100"
          },
          "logo_l": {
            "url": "//www.nhk.or.jp/common/img/media/gtv-200x200.png",
            "width": "200",
            "height": "200"
          }
        },
        "title": "チコちゃんに叱られる！▽痛いと手を当てるのはなぜ？▽晴れと曇りの境目は？ほか",
        "subtitle": "「なぜ女性はママになると不機嫌になるの？」「鉛筆はなぜ六角形なの？」チコちゃんが次々にくり出す素朴な疑問に、岡村隆史さんたち大人がタジタジに。話題満載の４５分。",
        "content": "ゲストは榊原郁恵さんとよゐこ濱口優さん、目を白黒させてチコちゃんに向き合います。「手を当てる理由」では脳の機能の奥深さが見えてきます。「晴れと曇り」では珍しい気象観測の現場に突撃、「ママが不機嫌」ではなんとプロフェッショナル＆ＮＨＫスペシャルとのコラボが実現します。誰もが使う鉛筆にも思わぬ工夫が。見逃しがちな疑問を家族や友人でぜひ話題にしてください。キョエちゃんコーナーにも仰天のお手紙が届きます。",
        "act": "【出演】岡村隆史，【ゲスト】榊原郁恵，濱口優，【リポーター】塚原愛，【声】木村祐一，【語り】森田美由紀",
        "genres": [
          "0515"
        ],
        "program_logo": {
          "url": "//www.nhk.or.jp/prog/img/4382/4382.jpg",
          "width": "640",
          "height": "640"
        },
        "program_url": "//nhk.jp/P4382",
        "hashtags": [
          "#チコちゃんに叱られる"
        ]
      }
    ]
  }
}
```

すべてのAPIは、ポータルサイト上で実際に動かしてみることができます。利用手続きなしで、いくつかのサンプルパラメータを設定して実際のレスポンスを見ることができるので、興味を持たれた方はまず試してみてください。最近ではあたりまえの機能になってきてますが、やっぱり便利！

#利用手続き

このAPIを利用するためには事前の手続きが必要です。ごく一般的な手続きで、難しいところはないと思いますが、以下にかんたんにまとめておきます：

1. ユーザー登録
[公式ポータルサイト](https://api-portal.nhk.or.jp)に行き、ページ右上「新規登録」からユーザーアカウントを作成します。このとき、必要な情報は基本的にメールアドレスだけです。実名とか住所とか勤務先とか、面倒な項目はありません。
ユーザ名を決め、必要な情報を入力して「アカウントの作成」をクリックするとメールが送られてきます。メール内のリンクをクリックしてポータルサイトのパスワードを設定すれば登録完了です。

2. アプリ登録
ポータルサイトにログインした状態では、ページ右上に自分の登録メールアドレスが表示され、それがメニューになっています。このメニューで「登録済みアプリ」を選んでアプリ一覧画面に進みます（「ユーザー情報の編集」画面から「My Apps」タブを選ぶことでも同じ画面に進めます）。
この画面で「新規アプリ登録」をクリックし、半角英数字で適当なアプリ名をつけて（「アプリのURL」は空でよい）「Create App」ボタンを押せばアプリ登録完了です。

3. APIキー確認
「登録済みアプリ」画面で、登録したアプリ名をクリックすると、英数字32文字からなるAPIキーが確認できます。すべてのAPIコールにはクエリパラメータkeyとしてこのAPIキーの値を渡す必要があります（上記の呼び出し例参照）。

#利用上の注意点

- 現在、1ユーザーが登録できるアプリ（=APIキー）は1個だけです。削除->再登録は可能です。
- APIを呼び出せる回数には以下の制限があります（1アプリごと）
    - Program List/Genre/Info API: 各300回/日
    - Now On Air API: 1,500回/日
- アクセスできる番組情報は当日から１週間先までです。過去の日付の情報にはアクセスできません。
- 現在のAPIバージョンはV2です。V2でアクセス期間が1週間に伸びたり（V1ではたしか2日）、出演者情報が追加されたりしています（[お知らせ](https://api-portal.nhk.or.jp/ja/blog)参照）。古いwrapperライブラリなどではV1のエンドポイントがハードコードされていたりするので注意が必要です。

#こうなったらいいな！

- 出演者情報がこんな↓文字列なわけですが、これがちゃんとJSON的に構造化されているとずいぶん使い勝手がよくなると思います。出演者部分に興味があるユーザー多いでしょうし。

```
"【出演】岡村隆史，【ゲスト】榊原郁恵，濱口優，【リポーター】塚原愛，【声】木村祐一，【語り】森田美由紀"
```
- 番組情報がもっと充実しているとさらに楽しいですよね。例えば、番組内で紹介された店・場所・サービスなどのURLとか、NHKオンデマンドへのリンクとか、関連タグなど。
- 最後になんといっても欲しいのは、全局対応です！正直、番組表はNHKだけでは利用価値はかなり限定的です。もし民放も全局同じフォーマットでAPI公開してくれたらどんなに便利なことか。民放各局の関係者の方々、ぜひご検討をお願いいたします（マネタイズのアイデアもありますよ！）

---
注）記事タイトルではネタで「5才」としていますが、ポータルサイトによるとこのAPIが公開されたのは2014.01.27だそうですので、この記事の公開時点では正確には4才です。