Niconico Snapshot Search API

https://site.nicovideo.jp/search-api-docs/snapshot
Admin
API for searching and analyzing niconico video content with filtering, sorting, and keyword search...
Tokens:7,123
Snippets:39
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### cURL Example for Nicovideo Search API

Source: https://site.nicovideo.jp/search-api-docs/snapshot

Example of how to execute a search query using cURL. This command searches for videos with '初音ミク' in the title, a view count greater than or equal to 10000, and sorts by view count.

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

--------------------------------

### Successful API Response Example

Source: https://site.nicovideo.jp/search-api-docs/snapshot

This is an example of a successful API response, including meta information like status, total count, and request ID, along with the requested data.

```json
{
  "meta": {
    "status": 200,
    "totalCount": 1,
    "id":"594513df-85ea-4122-9859-f4ec2701cacf"
  },
  "data": [
    {
      "contentId": "sm9",
      "title": "テスト",
      "description": "テスト",
      "startTime": "2016-11-03T02:09:11+09:00",
      "viewCounter": 1
    }
  ]
}
```

--------------------------------

### API Error Response Example (Maintenance)

Source: https://site.nicovideo.jp/search-api-docs/snapshot

An example of an API error response when the service is under maintenance. Users are advised to wait until maintenance is complete.

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

--------------------------------

### Search API URL Example

Source: https://site.nicovideo.jp/search-api-docs/snapshot

Example URL for searching videos. It includes parameters for query, targets, fields, filters, sorting, offset, limit, and context. Note that '+' may need to be URL-encoded as '%2B'.

```url
https://snapshot.search.nicovideo.jp/api/v2/snapshot/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
```

--------------------------------

### API Error Response Example (Internal Server Error)

Source: https://site.nicovideo.jp/search-api-docs/snapshot

An example of an API error response for an internal server error. It indicates a temporary issue and suggests retrying later.

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

--------------------------------

### Fetching Data Beyond Offset Limits using Filters

Source: https://site.nicovideo.jp/search-api-docs/snapshot

When the system's _offset limit is reached, use filters with startTime to retrieve data in ranges. This example shows how to fetch data for January and February 2019.

```http
# 2019年1月分を取得
filters[startTime][gte]=2019-01-01T00:00:00+09:00&filters[startTime][lt]=2019-02-01T00:00:00+09:00

# 2019年2月分を取得
filters[startTime][gte]=2019-02-01T00:00:00+09:00&filters[startTime][lt]=2019-03-01T00:00:00+09:00

...
```

--------------------------------

### API Error Response Example (Query Parse Error)

Source: https://site.nicovideo.jp/search-api-docs/snapshot

An example of an API error response when there is a query parse error. It includes status, error code, and a descriptive error message.

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

--------------------------------

### Successful Search API Response Example

Source: https://site.nicovideo.jp/search-api-docs/snapshot

This is a sample successful response from the search API, showing meta information and a list of videos matching the search criteria, including content ID, title, and view counter.

```json
{
  "meta": {
    "status": 200,
    "totalCount": 12673,
    "id": "0554268c-c0f3-4436-9098-7b9e07885623"
  },
  "data": [
    {
      "contentId": "sm1097445",
      "title": "【初音ミク】みくみくにしてあげる♪【してやんよ】",
      "viewCounter": 11904784
    },
    {
      "contentId": "sm1715919",
      "title": "初音ミク　が　オリジナル曲を歌ってくれたよ「メルト」",
      "viewCounter": 10230124
    },
    {
      "contentId": "sm15630734",
      "title": "『初音ミク』千本桜『オリジナル曲PV』",
      "viewCounter": 9557201
    }
  ]
}
```

--------------------------------

### Get Data Update Timestamp

Source: https://site.nicovideo.jp/search-api-docs/snapshot

Retrieves the timestamp indicating when the data referenced by the API was last updated.

```APIDOC
## GET /api/v2/snapshot/version

### Description
Retrieves the timestamp indicating the last modification time of the data available through the API.

### Method
GET

### Endpoint
https://snapshot.search.nicovideo.jp/api/v2/snapshot/version

### Response
#### Success Response
- **last_modified** (string) - The timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ss+09:00) indicating when the data was last updated.

#### Response Example
```json
{
  "last_modified" : "2023-10-27T05:00:00+09:00"
}
```
```

--------------------------------

### API Endpoint for Getting Data Modification Time

Source: https://site.nicovideo.jp/search-api-docs/snapshot

This endpoint provides the last modified timestamp for the data. The response is a JSON object containing the 'last_modified' field.

```json
{
  "last_modified" : "yyyy-MM-ddTHH:mm:ss+09:00"
}
```

--------------------------------

### 動画コンテンツ検索

Source: https://site.nicovideo.jp/search-api-docs/snapshot

キーワードやフィルタ条件を指定して動画コンテンツを検索します。User-Agentヘッダーにサービス名またはアプリケーション名を指定する必要があります。

```APIDOC
## GET /api/v2/snapshot/video/contents/search

### Description
キーワードやフィルタ条件を指定して動画コンテンツを検索します。User-Agentヘッダーにサービス名またはアプリケーション名を指定する必要があります。

### Method
GET

### Endpoint
https://snapshot.search.nicovideo.jp/api/v2/snapshot/video/contents/search

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

### ＊1 クエリ文字列仕様
#### AND検索
空白（半角）で区切る
例: ミク ボーカル
説明: "ミク" かつ "ボーカル"を含むコンテンツ

#### OR検索
ORで区切る
例: ミク OR ボーカル
説明: "ミク"または"ボーカル"を含むコンテンツ
備考: ORの前後には空白を入れてください。

#### OR検索 (複数)
例: ミク OR ボーカル OR ヴォーカル
説明: "ミク"または"ボーカル"または"ヴォーカル"を含むコンテンツ

#### AND・OR検索
例: ボーカル OR 歌ってみた ミク
説明: ("ボーカル" または"歌ってみた") でかつ "ミク" を含むコンテンツ
備考: ANDとORを組み合わせる場合OR検索を先に書きます。

#### フレーズ検索
ダブルクオート" で囲む
例: "ミク ボーカル"
説明: 空白を含む "ミク ボーカル" を含むコンテンツ
備考: ダブルクオートで囲むことで空白や演算子も含めて検索できます。

#### NOT検索
単語の前に-をつける
例: ミク -ボーカル
説明: "ミク"を含んでボーカルを含まないコンテンツ。

#### NOT検索 (ハイフン含む)
例: ミク - ボーカル
説明: "ミク" かつ "-" かつ "ボーカル"を含むコンテンツ
備考: - と単語の間に空白をいれないでください。

#### NOT検索 (単体エラー)
例: -ボーカル
説明: エラー。NOT検索だけ実行することはできません。

#### キーワード無し検索
空文字を指定する
例: search?q=&fields=...
説明: キーワードを使用せずに検索します。
備考: q=自体の省略はできません。負荷の高い検索となりますので、filtersと併用しヒット件数を10万件以内に絞り込んだ上でご利用ください。

### ＊2 フィールド仕様
すべてのフィールドで値が入ってないなどの理由でnullが返ってくる場合があります。
| フィールド名 | 説明 | 型 | fieldsで取得可能か | _sortに指定可能か | filtersに指定可能か |
|---|---|---|---|---|---|
| contentId | コンテンツID。https://nico.ms/ の後に連結することでコンテンツへのURLになります。 | string | o | - | o |
| title | タイトル | string | o | - | - |
| description | コンテンツの説明文。 | string | o | - | - |
| userId | ユーザー投稿動画の場合、投稿者のユーザーID | integer | o | - | - |
| channelId | チャンネル動画の場合、チャンネルID | integer | o | - | - |
| viewCounter | 再生数 | integer | o | o | o |
| mylistCounter | マイリスト数またはお気に入り数。 | integer | o | o | o |
| likeCounter | いいね！数 | integer | o | o | o |
| lengthSeconds | 再生時間(秒) | integer | o | o | o |
| thumbnailUrl | サムネイルのURL | string | o | - | - |
| startTime | コンテンツの投稿時間。 | string (ISO8601形式) | o | o | o |
| lastResBody | 最新のコメント | string | o | - | - |
| commentCounter | コメント数 | integer | o | o | o |
| lastCommentTime | 最終コメント時間 | string (ISO8601形式) | o | o | o |
| categoryTags | カテゴリタグ | string | o | - | o |
| tags | タグ(空白区切り) | string | o | - | o |
| tagsExact | タグ完全一致(空白区切り) | string | - | - | o |
| genre | ジャンル | string | o | - | o |
| genre.keyword | ジャンル完全一致 | string | - | - | o |
| contentType | 動画の種別 | enum('long','short') | 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のフィールド仕様を参考にしてください。
例
  * 再生数が100万のフィルタ

```
filters[viewCounter][0]=1000000
```

  * マイリスト数が1000以上かつコメント数が1000以上のフィルタ

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

  * 2014年に投稿されたコンテンツでフィルタ（日時はISO 8601形式のうち、YYYY-MM-DDThh:mm:ss±hh:mmのフォーマットで指定してください）

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

  * ジャンルがゲームのフィルタ

```
filters[genre][0]=ゲーム
```
```

--------------------------------

### Video Content Search

Source: https://site.nicovideo.jp/search-api-docs/snapshot

This endpoint allows you to search for video content on Nicovideo. You can specify search queries, targets, fields to retrieve, filters, sorting, and limits.

```APIDOC
## GET /api/v2/snapshot/video/contents/search

### Description
Searches for video content based on various criteria including keywords, targets, fields, filters, sorting, and limits.

### Method
GET

### Endpoint
https://snapshot.search.nicovideo.jp/api/v2/snapshot/video/contents/search

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query string.
- **targets** (string) - Optional - Specifies the fields to search within (e.g., 'title').
- **fields** (string) - Optional - Comma-separated list of fields to include in the response (e.g., 'contentId,title,viewCounter').
- **filters[field][operator]** (string) - Optional - Filters to apply to the search results. Examples:
  - `filters[viewCounter][gte]=10000` (greater than or equal to 10000 views)
  - `filters[startTime][gte]=YYYY-MM-DDTHH:mm:ss+09:00`
  - `filters[startTime][lt]=YYYY-MM-DDTHH:mm:ss+09:00`
- **_sort** (string) - Optional - Field to sort the results by. Prefix with '-' for descending order (e.g., '-viewCounter').
- **_offset** (integer) - Optional - Number of results to skip.
- **_limit** (integer) - Optional - Maximum number of results to return.
- **_context** (string) - Optional - Context for the request.

### Request Example
```json
{
  "q": "初音ミク",
  "targets": "title",
  "fields": "contentId,title,viewCounter",
  "filters": {
    "viewCounter": {
      "gte": "10000"
    }
  },
  "_sort": "-viewCounter",
  "_offset": 0,
  "_limit": 3,
  "_context": "apiguide"
}
```

### Response
#### Success Response (200)
- **meta** (object) - Response metadata.
  - **status** (integer) - HTTP status code (200 for success).
  - **totalCount** (integer) - Total number of matching results.
  - **id** (string) - Request ID.
- **data** (array) - Array of content objects matching the search criteria.
  - **contentId** (string) - The unique identifier for the content.
  - **title** (string) - The title of the content.
  - **viewCounter** (integer) - The number of views for the content.

#### Response Example
```json
{
  "meta": {
    "status": 200,
    "totalCount": 12673,
    "id": "0554268c-c0f3-4436-9098-7b9e07885623"
  },
  "data": [
    {
      "contentId": "sm1097445",
      "title": "【初音ミク】みくみくにしてあげる♪【してやんよ】",
      "viewCounter": 11904784
    },
    {
      "contentId": "sm1715919",
      "title": "初音ミク　が　オリジナル曲を歌ってくれたよ「メルト」",
      "viewCounter": 10230124
    },
    {
      "contentId": "sm15630734",
      "title": "『初音ミク』千本桜『オリジナル曲PV』",
      "viewCounter": 9557201
    }
  ]
}
```

#### Error Response (400)
- **meta** (object) - Response metadata.
  - **status** (integer) - HTTP status code (400 for bad request).
  - **errorCode** (string) - Error code (e.g., 'QUERY_PARSE_ERROR').
  - **errorMessage** (string) - Description of the error.

#### Error Response (500)
- **meta** (object) - Response metadata.
  - **status** (integer) - HTTP status code (500 for internal server error).
  - **errorCode** (string) - Error code ('INTERNAL_SERVER_ERROR').
  - **errorMessage** (string) - Description of the error.

#### Error Response (503)
- **meta** (object) - Response metadata.
  - **status** (integer) - HTTP status code (503 for service unavailable).
  - **errorCode** (string) - Error code ('MAINTENANCE').
  - **errorMessage** (string) - Description of the error.
```

--------------------------------

### JSON Filter for Specific Dates

Source: https://site.nicovideo.jp/search-api-docs/snapshot

Use this JSON structure to filter content posted on specific dates in 2016 and 2017. Ensure dates are in ISO 8601 format.

```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_lower": true
    },
    {
      "type": "range",
      "field": "startTime",
      "from": "2016-07-07T00:00:00+09:00",
      "to": "2016-07-08T00:00:00+09:00",
      "include_lower": true
    }
  ]
}
```
Tokens:
Raw