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.

Headers

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

Query parameters

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

Parameter Type Optional Default Value An example Description
q string no - game keyword to search. Please refer to * 1 for details of format.
targets string no - title,description,tags Field (s) to be searched for (comma separated values). For keyword search, please specify title, description, tags. In the case of tag search (hits content with a tag exactly matching the keyword), please specify tagsExact.
fields string yes - contentId,title,description,tags Field (s) of the content that you want to include in the response (s), separated by commas. Please refer to * 2 for the field name.
filters string yes - - Filter search results only to content that matches filter criteria. See * 3 for the filter format.
_sort string no - -viewCounter Specify the sort order by concatenating the sort direction sign and the field name. Whether the sorting direction is ascending or descending is specified by '+' or '-', otherwise it defaults to '-'. Please refer to * 2 for available fields.
_offset integer yes 0 10 Offset of returning content. Maximum: 1600
_limit integer yes 10 10 Maximum number of returned contents. Maximum: 100
_context string no - apiguide Service or application name. Maximum: 40 characters

*1 Query string specification

Feature Format Example Description Memo
AND Search Separate by brank miku vocal Contents indluding “miku” AND “Vocal"
OR Search ORで区切る miku OR miku Contents indluding “miku” OR “Vocal" Please put a blank before or after OR.
- - miku OR vocal OR vocaloid Contents indluding “miku” OR “vocal" OR “vocaloid"
AND・OR Search - vocal OR song miku Contents indluding “miku” OR “vocal" AND “vocaloid" Write OR search first when combining AND and OR.
Phrase search Double-quote" で囲む “miku vocal” Contents including “miku vocal” By enclosing it with double quotes you can search including whitespace and operators.
NOT Search Put -(minus) in front of word miku -vocal Content not including vocals including "Miku".
- - miku - miku Contents including "miku” AND “-” AND “vocal" Don't put a space between - and the word.
- - -vocal Error Can't execute only NOT search

*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.

Field Description Type Enable to get by `fields` Enable to set in `sort` Enable to get by `filters`
contentId Content ID. Concat after http://nico.ms/ then it becomes the URL to the content. string o - o
title title string o - -
description description of the content string o - -
tags tag(blank separated) attached in the content string o - o
categoryTags tag of category string o - o
viewCounter number of view or visit integer o o o
mylistCounter number of my lists or favorites integer o o o
commentCounter number of comments integer o o o
startTime time contents posted / time live broadcast started string (ISO8601) o o o
thumbnailUrl URL of thumbnail image string - o -
communityIcon URL of community icon string o - -
scoreTimeshiftReserved number of timeshift reserved(live only) integer - o -
liveStatus Broadcast status (past broadcast / live broadcast / scheduled broadcast) (live only) enum('past','onair','reserved') o - o

*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:

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]=GAME
filters[liveStatus][0]=onair

Response

Return the following JSON

Regular

Field Type Example Description
meta object - Meta info of response
meta.status integer 200 HTTP Status (success)
meta.id string 54fbd5ff-df0c-42fd-8ddf-f64f73ad21b2 Request ID
meta.totalCount integer 12673 Number of Hit contents
data array - Hit the content. The elements depend on field parameter

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

Field Type Example Description
meta object - Meta info of response
meta.status integer 400 HTTP Status (error)
meta.errorCode string QUERY_PARSE_ERROR Error code
meta.errorMessage string query parse error Detail of 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

URL

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

Changelog