Niconico Search API Reference

Introduction

This document explains how to use API to search contents of niconico. Search API allows to return the contents of niconico by specifying keywords and filters.

API Endpoint

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

URI parameter

Must set one of the following target services at :service in the endpoint. Sorry, now we don't have an API to search for multiple services at same time.

• video video
• live live
• illust illustation
• manga manga(cartoon)
• book book
• channel channel(simmilar to community)
• channelarticle blog
• news news
• game game

Headers

Specify the following headers as much as possible. It's not complacency, but it's convinient for us to examine requests.

• User-Agent: Name of the service or application. Maximum: 40 characters.

Query parameters

As give some options API, set the following parameters through GET query parameters.

＊1 Query string specification

＊2 Field Specification

Some fields does not allow to use in certain service. In addition, you may get null value for some reasons such as a content doesn't have some fields.

＊3 filter specification

If you want to filter only content whose field field 0 matches one of val 0 or val 1 ... values, specify the URL parameter as follows:

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

To filter only contents whose field field 1 matches the range of val 0 to val 1 (not including val 0 and val 1), specify the URL parameter as follows.

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

If you want to include range values ​​also use gte and lte.

You can use integer or string fields by filters. For details, refer to the field specification of * 2.

Example:

• Filter by 1 million view

filters[viewCounter][0]=1000000

• Filter by number of 1000 mylists or over 1000 comments

filters[mylistCounter][gte]=1000&filters[commentCounter][gte]=1000

• Filter by posting in 2014

filters[startTime][gte]=2014-01-01T00:00:00+09:00&filters[startTime][lt]=2015-01-01T00:00:00+09:00

• Filter category tags for games

filters[categoryTags][0]=GAME

• Filter lives on air only

filters[liveStatus][0]=onair

Response

Return the following JSON

Regular

Example:

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

Error

status: 400

Invalid parameters

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

status: 500

Internal error of search servers

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

status: 503

Search service is in middle of maintenance

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

Sample query and execution

Show the specified query for the following condigions

• includes "MIKU"
• view counter is more than 10000
• information to need to get content_id,title and view counter
• sorts ordered by view_counter asc and limits 3 items

URL

• + in an example requires to be url encoded by %2B

http://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

An example output by using curl

curl -A 'apiguide application' 'http://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=MIKU " --data-urlencode "filters[viewCounter][gte]=10000"

A response

{
  "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
    }
  ]
}