niconico コンテンツ検索APIガイド
自作サービス/ツールからniconicoのコンテンツを検索できます


はじめに

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

APIエンドポイント

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

URIパラメータ

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

ヘッダー

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

クエリパラメータ

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

パラメータ名省略可能かデフォルト値説明
qstringno-ゲーム検索キーワードです。 書式の詳細は*1を参照してください。
targetsstringno-title,description,tags検索対象のフィールド(複数可、カンマ区切り)です。キーワード検索の場合、title,description,tagsを指定してください。タグ検索(キーワードに完全一致するタグがあるコンテンツをヒット)の場合、tagsExactを指定してください。
fieldsstringyes-contentId,title,description,tagsレスポンスに含みたいヒットしたコンテンツのフィールド(複数可、カンマ区切り)です。フィールド名は*2を参照してください。
filtersstringyes--検索結果をフィルタの条件にマッチするコンテンツだけに絞ります。フィルタの書式には*3を参照してください。
jsonFilterstringyes--OR や AND の入れ子など複雑なフィルター条件を使う場合のみに使用します。 OR / AND / NOT 単体で使用する場合は filters を使ってください。フィルタの書式には*4を参照してください。
_sortstringno--viewCounterソート順をソートの方向の記号とフィールド名を連結したもので指定します。ソートの方向は昇順または降順かを'+'か'-'で指定し、ない場合はデフォルトとして'-'となります。使用できるフィールドは*2を参考にしてください。
_offsetintegeryes010返ってくるコンテンツの取得オフセット。最大:1600
_limitintegeryes1010返ってくるコンテンツの最大数。最大:100
_contextstringno-apiguideサービスまたはアプリケーション名。最大:40文字

*1 クエリ文字列仕様

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

*2 フィールド仕様

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

フィールド名説明fieldsで取得可能か_sortに指定可能かfiltersに指定可能か
contentIdコンテンツID。https://nico.ms/ の後に連結することでコンテンツへのURLになります。stringo--
titleタイトルstringo--
descriptionコンテンツの説明文。stringo--
tagsタグ(空白区切り)stringo-o
categoryTagsカテゴリタグstringo-o
viewCounter再生数または来場者数。integerooo
mylistCounterマイリスト数またはお気に入り数。integerooo
commentCounterコメント数integerooo
startTimeコンテンツの投稿時間または生放送の開始時間。string (ISO8601形式)ooo
lastCommentTime最終コメント時間integerooo
lengthSeconds再生時間(秒)integerooo
thumbnailUrlサムネイルのURLstringo--
communityIconコミュニティアイコンのURLstringo--
scoreTimeshiftReserved(生放送のみ)タイムシフト予約者数integerooo
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フィルタ指定仕様

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

キー説明
共通typeequal,range,or,and,notのいずれか
type == equalfieldequal で対象にしたいフィールド
valueequal で対象にしたい値
type == rangefieldrange で対象にしたいフィールド
from範囲の始点の値
to範囲の終点の値
include_lowerfromの値を範囲に含めるか (デフォルト true)
include_uppertoの値を範囲に含めるか (デフォルト true)
type == orfiltersJSONフィルターの配列
type == andfiltersJSONフィルターの配列
type == notfilterJSONフィルター
{
  "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が返ってきます。

正常な場合

フィールド名説明
metaobject-レスポンスのメタ情報フィールド
meta.statusinteger200HTTPステータス(成功の場合200)
meta.idstring54fbd5ff-df0c-42fd-8ddf-f64f73ad21b2リクエストID
meta.totalCountinteger12673ヒット件数
dataarray-ヒットしたコンテンツ。要素の内容はパラメータ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
    }
  ]
}

エラーの場合

フィールド名説明
metaobject-レスポンスのメタ情報フィールド
meta.statusinteger400HTTPステータス(エラーの場合200以外)
meta.errorCodestringQUERY_PARSE_ERRORエラーコード
meta.errorMessagestringquery 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利用規約

この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日 制定

更新履歴