Ruby - ニコニコ動画の検索APIラッパーを作りました #Ruby

概要

ニコニコ動画『スナップショット検索API』ガイドで公開されている検索用APIをRubyから呼び出すためのライブラリです。

インストール

Gemfileに

Gemfile

gem 'nico_search_snapshot'

と書くか、コマンドラインから

コマンドライン

gem install nico_search_snapshot

使い方

require 'nico_search_snapshot'

nico = NicoSearchSnapshot.new('アプリケーション名')
results = nico.search('query')

results.each do |r|
  puts r.cmsid # -> "sm12345"
  puts r.title # -> "動画のタイトル"
  puts r.description # -> "動画の説明文"
end

newするときに、APIを使用するアプリケーション/サービス名(最大40文字)を渡してください。APIのissuerパラメータに渡しています。APIの利用状況把握のために使用されるそうです。

resultsには検索結果のリストが入ってきます。検索結果は以下のプロパティを持っています

プロパティ	内容
cmsid	動画ID
title	動画のタイトル
description	動画の説明文
tags	動画のタグ
start_time	動画の投稿日時
thumbnail_url	動画のサムネイルURL
view_counter	再生数
comment_counter	コメント数
mylist_counter	マイリスト数
last_res_body	直近のコメント
length_seconds	動画の再生時間(秒)

検索結果の件数

デフォルトでは検索結果の先頭から10件を取得するようになっています。:fromと:sizeオプションで開始と件数を指定できます。

results = nico.search('query', size: 100) # 先頭100個
results = nico.search('query', size: 100, from: 200) # 201〜300個目

:allオプションを指定すると全件取得できます。このgem独自のオプションです。検索結果の終わりに達するまでリクエストを繰り返します。運営に怒られたらごめんなさい。

results = nico.search('query', all: true)

キーワード検索とタグ検索

:searchオプションで、キーワード検索かタグ検索かを指定します。

# キーワード検索
nico.search('query', search: [:title, :description, :tags]) 
# タイトルだけを対象に検索
nico.search('query', search: [:title]) 

# タグ検索
nico.search('query', search: [:tags_exact])

フィルタ

検索結果にフィルタをかけることができます。
:filterオプションに抽出条件のリストを渡します。条件指定の仕方は以下の通りです。公式ドキュメントにもっと詳しい情報が載っていますので、参照してみてください。

# 再生時間が5分きっかりの動画だけ抽出する
nico.search('query', filters: [{
  type: :equal, field: :length_seconds, value: 300}])

# 2015年1月1日から1月31日までの間に投稿された、かつ再生数1万を超える動画だけを抽出する
results = nico.search('hello', filters: [
  {type: :range,
   field: :start_time,
   from: '2015-01-01 00:00:00',
     to: '2015-02-01 00:00:00',
   include_upper: false # <- 終端(2015-02-01 00:00:00)を含まない
  },
  {type: :range, field: :view_counter,
   from: 10000,
   include_lower: false # <- 開始(10,000)を含まない
  }])

ソート

:sort_byと:orderオプションで検索結果の並び順を指定することができます。
指定できるフィールドは以下の通りです。

フィールド名
last_comment_time
view_counter
start_time
mylist_counter
comment_counter
length_seconds

:orderオプションは:ascが昇順で:descが降順です。

nico.search('query', sort_by: :view_counter, order: asc)

ソースコード

RDoc

拙い英語でRDocのコメントを書いてみたのですが、意味が通っているのか自分でもわかりません。誰か英語を教えてください。