niconico コンテンツ検索APIガイド

はじめに

本ドキュメントは、niconicoのコンテンツを検索するAPIについて解説するものです。 キーワードやフィルタ条件を指定して、niconicoのコンテンツを検索できます。

APIエンドポイント

https://api.search.nicovideo.jp/api/v2/:service/contents/search

URIパラメータ

エンドポイント中の :service に以下の検索対象のサービスのいずれかを指定します。

ヘッダー

できるだけ以下のヘッダーを指定してください。

クエリパラメータ

以下のパラメータを GET のクエリパラメータで与えます。

パラメータ名 型 省略可能か デフォルト値 例 説明
q string no - ゲーム 検索キーワードです。 書式の詳細は＊1を参照してください。
targets string no - title,description,tags 検索対象のフィールド（複数可、カンマ区切り）です。キーワード検索の場合、title,description,tagsを指定してください。タグ検索（キーワードに完全一致するタグがあるコンテンツをヒット）の場合、tagsExactを指定してください。
fields string yes - contentId,title,description,tags レスポンスに含みたいヒットしたコンテンツのフィールド（複数可、カンマ区切り）です。フィールド名は＊2を参照してください。
filters string yes - - 検索結果をフィルタの条件にマッチするコンテンツだけに絞ります。フィルタの書式には＊3を参照してください。空文字はnull扱いになります。
jsonFilter string yes - - OR や AND の入れ子など複雑なフィルター条件を使う場合のみに使用します。 OR / AND / NOT 単体で使用する場合は filters を使ってください。フィルタの書式には＊4を参照してください。
_sort string no - -viewCounter ソート順をソートの方向の記号とフィールド名を連結したもので指定します。ソートの方向は昇順または降順かを'+'か'-'で指定し、ない場合はデフォルトとして'-'となります。使用できるフィールドは＊2を参考にしてください。nullになっているコンテンツはソートの方向に関わらず最後になります。
_offset integer yes 0 10 返ってくるコンテンツの取得オフセット。最大:1600
_limit integer yes 10 10 返ってくるコンテンツの最大数。最大:100
_context string no - apiguide サービスまたはアプリケーション名。できるだけ指定してください。最大:40文字

＊1 クエリ文字列仕様

機能名 書式 例 説明 備考
AND検索 空白（半角）で区切る ミク ボーカル "ミク" かつ "ボーカル"を含むコンテンツ
OR検索 ORで区切る ミク OR ボーカル "ミク"または"ボーカル"を含むコンテンツ ORの前後には空白を入れてください。
- - ミク OR ボーカル OR ヴォーカル "ミク"または"ボーカル"または"ヴォーカル"を含むコンテンツ
AND・OR検索 - ボーカル OR 歌ってみた ミク ("ボーカル" または"歌ってみた") でかつ "ミク" を含むコンテンツ ANDとORを組み合わせる場合OR検索を先に書きます。
フレーズ検索 ダブルクオート" で囲む "ミク ボーカル" 空白を含む "ミク ボーカル" を含むコンテンツ ダブルクオートで囲むことで空白や演算子も含めて検索できます。
NOT検索 単語の前に-をつける ミク -ボーカル "ミク"を含んでボーカルを含まないコンテンツ。
- - ミク - ボーカル "ミク" かつ "-" かつ "ボーカル"を含むコンテンツ - と単語の間に空白をいれないでください。
- - -ボーカル エラー NOT検索だけ実行することはできません。

＊2 フィールド仕様

サービスによって使用できないフィールドがあります。また、すべてのフィールドで値が入ってないなどの理由でnullが返ってくる場合があります。

video フィールド仕様
フィールド名 説明 型 fieldsで取得可能か _sortに指定可能か filtersに指定可能か
contentId コンテンツID。https://nico.ms/ の後に連結することでコンテンツへのURLになります。 string o - -
title タイトル string o - -
description コンテンツの説明文 string o - -
userId 投稿者のID integer o o o
viewCounter 再生数 integer o o o
mylistCounter マイリスト数 integer o o o
lengthSeconds 再生時間(秒) integer o o o
thumbnailUrl サムネイルのURL string o - -
startTime 動画の投稿時間 string (ISO8601形式) o o o
threadId スレッドのID integer o o o
commentCounter コメント数 integer o o o
lastCommentTime 最終コメント時間 string (ISO8601形式) o o o
categoryTags カテゴリタグ string o - o
channelId チャンネルのID integer o o o
tags タグ(空白区切り) string o - o
tagsExact タグ完全一致(空白区切り) string - - o
lockTagsExact ロックされたタグ完全一致(空白区切り) string o - o
genre ジャンル string o - o
genre.keyword ジャンル完全一致 string o - o
live フィールド仕様
フィールド名 説明 型 fieldsで取得可能か _sortに指定可能か filtersに指定可能か
contentId コンテンツID。https://nico.ms/ の後に連結することでコンテンツへのURLになります。 string o - -
title タイトル string o - -
description コンテンツの説明文。 string o - -
userId 放送者のID integer o o o
channelId チャンネルID integer o o o
communityId コミュニティID integer o o o
providerType 放送元種別 enum('official','community','channel') o - o
tags タグ(空白区切り) string o - o
tagsExact タグ完全一致(空白区切り) string - - o
categoryTags カテゴリタグ string o - o
viewCounter 来場者数 integer o o o
commentCounter コメント数 integer o o o
openTime 生放送の開場時間 string (ISO8601形式) o o o
startTime 生放送の開始時間 string (ISO8601形式) o o o
liveEndTime 生放送の終了時間 string (ISO8601形式) o o o
timeshiftEnabled タイムシフト視聴可能か boolean o - o
scoreTimeshiftReserved タイムシフト予約者数 integer o o o
thumbnailUrl サムネイルのURL string o - -
liveScreenshotThumbnailSmall 放送中のサムネイルのURL string o - -
tsScreenshotThumbnailSmall タイムシフトのサムネイルのURL string o - -
communityText コミュニティ名 string o - o
communityIcon コミュニティアイコンのURL string o - -
memberOnly チャンネル・コミュニティ限定か boolean o - o
liveStatus 放送ステータス（過去放送/生放送中/予約放送） enum('past','onair','reserved') o - o

＊3 フィルタ指定仕様

フィールド field0 が val0 または val1 ... の値のいずれかに一致するコンテンツだけにフィルタリングする場合、以下のようにURLパラメータを指定します。

filters[field0][0]=val0&filters[field0][1]=val1

フィールド field1 が val0 〜 val1 の範囲（val0,val1含まず）に一致するコンテンツだけにフィルタリングする場合、以下のようにURLパラメータを指定します。

 filters[field1][gt]=val0&filters[field1][lt]=val1

範囲の値も含めたい場合gteとlteを使用します。

フィルタにはinteger、またはstring(日付)のフィールドを利用できます。詳しくは＊2のフィールド仕様を参考にしてください。

例

filters[viewCounter][0]=1000000
filters[mylistCounter][gte]=1000&filters[commentCounter][gte]=1000
filters[startTime][gte]=2014-01-01T00:00:00+09:00&filters[startTime][lt]=2015-01-01T00:00:00+09:00
filters[categoryTags][0]=ゲーム
filters[liveStatus][0]=onair

＊4 JSONフィルタ指定仕様

実際に使用する際はエンコードする必要があります。

キー 説明
共通 type equal,range,or,and,notのいずれか
type == equal field equal で対象にしたいフィールド
value equal で対象にしたい値
type == range field range で対象にしたいフィールド
from 範囲の始点の値
to 範囲の終点の値
include_lower fromの値を範囲に含めるか (デフォルト true)
include_upper toの値を範囲に含めるか (デフォルト true)
type == or filters JSONフィルターの配列
type == and filters JSONフィルターの配列
type == not filter JSONフィルター 
{
  "type": "or",
  "filters": [
    {
      "type": "range",
      "field": "startTime",
      "from": "2017-07-07T00:00:00+09:00",
      "to": "2017-07-08T00:00:00+09:00",
      "include_upper": false
    },
    {
      "type": "range",
      "field": "startTime",
      "from": "2016-07-07T00:00:00+09:00",
      "to": "2016-07-08T00:00:00+09:00",
      "include_upper": false
    }
  ]
}

レスポンス

以下のJSONが返ってきます。

正常な場合

フィールド名 型 例 説明
meta object - レスポンスのメタ情報フィールド
meta.status integer 200 HTTPステータス（成功の場合200）
meta.id string 54fbd5ff-df0c-42fd-8ddf-f64f73ad21b2 リクエストID
meta.totalCount integer 12673 ヒット件数
data array - ヒットしたコンテンツ。要素の内容はパラメータfieldsによって異なります

例

{
  "meta": {
    "status": 200,
    "totalCount": 1,
    "id":"54fbd5ff-df0c-42fd-8ddf-f64f73ad21b2"
  },
  "data": [
    {
      "contentId": "sm9",
      "title": "テスト",
      "description": "テスト",
      "startTime": "2015-04-31T00:00:00+09:00",
      "viewCounter": 1
    }
  ]
}

エラーの場合

フィールド名 型 例 説明
meta object - レスポンスのメタ情報フィールド
meta.status integer 400 HTTPステータス（エラーの場合200以外）
meta.errorCode string QUERY_PARSE_ERROR エラーコード
meta.errorMessage string query parse error エラー内容

status: 400

不正なパラメータです。

{
  "meta": {
    "status": 400,
    "errorCode": "QUERY_PARSE_ERROR",
    "errorMessage": "query parse error"
  }
}

status: 500

検索サーバの異常です。

{
  "meta": {
    "status": 500,
    "errorCode": "INTERNAL_SERVER_ERROR",
    "errorMessage": "please retry later."
  }
}

status: 503

サービスがメンテナンス中です。メンテナンス終了までお待ち下さい。

{
  "meta": {
    "status": 503,
    "errorCode": "MAINTENANCE",
    "errorMessage": "please retry later."
  }
}

サンプルクエリと実行例

ここでは、以下のような条件の検索クエリを例示します。

URL

https://api.search.nicovideo.jp/api/v2/video/contents/search?q=%E5%88%9D%E9%9F%B3%E3%83%9F%E3%82%AF&targets=title&fields=contentId,title,viewCounter&filters[viewCounter][gte]=10000&_sort=-viewCounter&_offset=0&_limit=3&_context=apiguide

curl での実行例

curl -A 'apiguide application' 'https://api.search.nicovideo.jp/api/v2/video/contents/search?targets=title&fields=contentId,title,viewCounter&_sort=-viewCounter&_offset=0&_limit=3&_context=apiguide' --data-urlencode "q=初音ミク" --data-urlencode "filters[viewCounter][gte]=10000"

レスポンス

{
  "meta": {
    "status": 200,
    "totalCount": 12673,
    "id": "54fbd5ff-df0c-42fd-8ddf-f64f73ad21b2"
  },
  "data": [
    {
      "contentId": "sm1097445",
      "title": "【初音ミク】みくみくにしてあげる♪【してやんよ】",
      "viewCounter": 11904784
    },
    {
      "contentId": "sm1715919",
      "title": "初音ミク　が　オリジナル曲を歌ってくれたよ「メルト」",
      "viewCounter": 10230124
    },
    {
      "contentId": "sm15630734",
      "title": "『初音ミク』千本桜『オリジナル曲PV』",
      "viewCounter": 9557201
    }
  ]
}

制限事項

IPアドレス等による利用制限を設けています。制限を超えてリクエストを行った場合、正常に検索結果が返されません。

こちらのAPIの商用利用はできません。

CORS (Cross-Origin Resource Sharing) には対応しません。

API利用規約

このAPI利用規約（以下「本利用規約」といいます）は、株式会社ドワンゴ（以下「当社」といいます）が企画・運営するサービス「niconico」のAPI（以下「本API」といいます）を、当社企画その関連イベント(以下総称して対象イベント」といいます)に応募するアプリケーション（以下単に「アプリケーション」といいます）向けに公開するにあたって、本APIの利用者（以下「利用者」といいます）が本APIを利用するにあたっての諸条件について規定します。利用者は本APIを利用する前に、必ず本利用規約をご確認いただいた上、本利用規約にご同意いただく必要があります。当社は、利用者が本APIを利用したことをもって本利用規約に同意したものとみなします。

なお、本利用規約は、当社の任意の判断により、変更されることがあります。当社は、変更後の利用規約が掲示された以降に利用者が本APIを利用したことをもって、変更後の利用条件に利用者が承諾したものとみなします。

第1条　（本APIの利用許諾）
1.  当社は、利用者に対し、本API及び本APIに関して提供されるドキュメント（以下「本ドキュメント」といいます）を利用することを許諾します。但し、利用者は、本利用規約及び本ドキュメントに記載された態様、方法に従って本APIを利用するものとします。
2.  当社は、以下の事由により、一時的に本APIの利用を停止することがあります。
(1) 当社によるシステムの保守、点検、修理などを行う場合
(2) 火災・停電によりサービスの提供ができなくなった場合
(3) 天変地異などによりサービスの提供ができなくなった場合
(4) その他、運用上又は技術上、サービス提供の一時的な中断を必要とした場合

第2条　（知的財産権等）
1.  本APIに関する著作権、商標権、意匠権、特許権、実用新案権、ノウハウ、その他権利の一切（以下「知的財産権等」といいます）は、当社に帰属します。
2.  利用者は、本API及び当社の知的財産権等を、本利用規約において明示的に許諾している範囲を超えて利用したりすることはできません。
3.  前項に違反して、利用者が当社に損害を与えた場合、利用者はこの損害（間接的損害も含みます）を当社に対し賠償するものとします。

第3条（禁止事項）
利用者は、本APIの利用（エンドユーザーによるアプリケーション利用に伴う場合を含む）にあたり、以下に該当する行為をすることはできません。利用者が以下の項目の一つにでも該当した場合、当社は、利用者に対して何等の催告もなく、本APIの利用を停止することができるものとし、またこれにより、当社に損害が生じた場合、利用者はこの損害（間接的損害も含みます）を当社に対し賠償するものとします。
(1) 本ドキュメントに記載されてない方法、態様での本APIの利用
(2) 本ドキュメントの複製、改変、翻訳、第三者への頒布、送信（自動公衆送信、送信可能化を含む）。但し、著作権法上の「引用」に該当する場合を除く。
(3) niconicoの機能・性能に悪影響を与えたり妨害したりする行為
(4) 公序良俗に反する行為（反社会的活動及びその宣伝活動も含む）
(5) 犯罪的行為（コンピュータウィルス・ジャンクメール・スパムメール・チェーンレターその他有害なファイルのアップロードや配布、殺人幇助、未成年者略取、ねずみ講にあたる行為を含む）及び、当該犯罪的行為を助長し又はその実行を暗示する行為
(6) 当社、他の利用者、又は第三者の知的所有権を侵害する行為
(7) 当社、他の利用者、又は第三者の財産・信用・名誉等を毀損する行為及び、プライバシーに関する権利、肖像権その他の権利を侵害する行為
(8) 故意、過失を問わず、法令、条約に反する行為
(9) 当社、他の利用者、又は第三者に経済的・精神的不利益を与える行為
(10) 当社、他の利用者、又は第三者に対する誹謗中傷、いやがらせの行為
(11) 公職選挙法に抵触する行為
(12) 未成年者に対し悪影響があると判断される行為
(13) 性風俗、宗教、政治に関する社会的行為であると判断される行為
(14) niconicoその他当社が提供する全てのサービスの運営を妨げる行為､又はそのおそれのある行為をしていると当社が判断した行為
(15) niconico及び当社が提供する全てのサービスの信用・名誉等を毀損する行為､又はそのおそれのある行為
(16) 本利用規約の条項に違反する行為
(17) 個人に関する情報の収集、蓄積行為
(18) 「niconico規約」の禁止事項に該当する場合
(19) その他、当社が不適当と判断する行為

第4条（免責）
1.  利用者は、本APIの利用（エンドユーザーによるアプリケーションの利用に伴う場合を含む）を、利用者自身の責任の下で行うものとします。当該利用に関わる一切の危険は利用者のみが負うものであり、当社は一切関与せず一切の責任も負わないことを利用者はここに確認し、同意するものとします。
2.  当社は、本APIに関し、その確実性、正確性、安全性、有用性、第三者権利侵害の有無、及び特定目的への適合性のいずれについても保証するものではありません。
3.  本APIは、ご利用開始時点における本APIと同等の利用環境を永続的に保証するものではありません。
4.  利用者は、本APIの利用（エンドユーザーによるアプリケーションの利用に伴う場合を含む）に起因して発生した一切の直接・間接の損害（データ滅失、サーバーダウン、業務停滞、第三者からのクレーム等、これらに限らない）ないし危険はすべて利用者のみが負うことをここに確認し、当社は一切関与せず一切の責任も負わないものとします。

第5条（利用者の責任）
本利用規約違反又は第三者の知的財産権、肖像権、プライバシーに関する権利、その他の権利の侵害に起因又は関連して生じたすべてのクレームや請求については、利用者の費用と責任において解決するものとし、当社は一切関与せず一切の責任も負いません。また、当該クレームや請求への対応に関連して当社に費用が発生した場合又は損害賠償金等の支払いを行った場合については、利用者は当社に対し当該費用及び損害賠償金等（当社が支払った弁護士費用を含みます）を支払うものとします。

第6条（本APIの変更・終了）
1.  本APIは、利用者への事前の通知なくして変更されることがあります。利用者はこれを予め了承するものとし、当該変更に伴い、利用者又は第三者に不利益又は損害が発生したとしても、当社は一切その責任を負わないものとします。
2.  当社は本APIを、対象イベントの開催期間に拘らず、利用者に対する事前の予告なくして停止又は終了することができます。当該停止又は終了に伴い、利用者又は第三者に不利益又は損害が発生したとしても、当社は一切その責任を負わないものとします。

第7条（分離性）
本利用規約に定める条項の一部が強行法規への抵触その他の理由により無効とされた場合であっても、当該無効とされた条項以外の他の条項は有効に存続するものとします。この場合、当該無効とされた条項は、当初に意図された経済的目的が可能な限り達成できる有効な条項に当然に置き換えられるものとし、利用者はこれを予め承諾するものとします。

第8条（利用者の責任）
本利用規約及び利用者と当社の関係については、日本法を準拠法とし、万一紛争が生じた場合には、東京地方裁判所又は東京簡易裁判所を第一の専属的管轄裁判所とします。


2015年11月19日　制定

更新履歴