HeartRails Capture は、特定の URL の後に対象ページの URL をつなげて指定すると、直接そのページのサムネイル画像を返します。
例えば、次の URL は、"http://www.mozilla-japan.org" のサムネイル画像になります。
ただし、指定の URL に対するサムネイル画像がまだ作られていない場合は、"Now Capturing" と書かれた画像が返されます。
このとき、HeartRails Capture のサーバーでは順次リクエストを受けてサムネイル画像の作成を行っていますので、しばらくしてからまたアクセスしてみてください。
http://capture.heartrails.com/?http://www.mozilla-japan.org
また、対象ページの URL の前にオプションをつけると、サムネイル画像のサイズや装飾等を変更することができます。
例えば、次の URL は横 200 ピクセル、縦 400 ピクセルで影つきのサムネイル画像となります。
http://capture.heartrails.com/200x400/shadow?http://www.mozilla-japan.org
フリーサイズ・オプション: 横サイズ x 縦サイズ
表示するサムネイル画像のサイズを、横サイズと縦サイズのピクセル数で指定することができます。
横サイズは 40 ～ 400 の範囲で、縦サイズは横サイズの 0.5 倍 ～ 3.75 倍の範囲で設定が可能です。
固定サイズ・オプション: tiny, small, medium, large, huge
フリーサイズではなく、あらかじめ用意された既定のサイズを small や large といったキーワードで指定することもできます。
装飾オプション: shadow, border, round, bg, shorten
shadow, border, round を指定すると、それぞれ影つき、縁つき、角丸めをサムネイル画像に付加することができます。
影つきや角丸めの指定時に、デフォルトでは背景色が白 （RGB コード "ffffff"） になりますが、"bg=" の後に 6 桁の RGB コードをつなげたオプションを指定することで、背景色を変更できます。
また、shorten をつけると、対象ページの縦：横の比率が指定サイズの比率よりも小さいときに、対象ページに合わせてサムネイル画像の縦サイズを縮めることができます。
これらのオプションは、フリーサイズの指定時のみ有効です。また、装飾のオプションは組み合わせて指定できます。
PDF オプション: pdf
PDF ファイルによるスナップショットは、PDF オプションを指定することで取得できます。
例えば、次の URL へアクセスすると PDF が表示されます。ただし、PDF がまだ作られていない場合は、"Now capturing" と書かれたテキストが返されます。
http://capture.heartrails.com/pdf?http://www.mozilla-japan.org
ディレイ・オプション: delay
対象ページの読み込みが完了してからサムネイル画像を作成するまでの時間を、秒単位で指定するオプションです。
0 ～ 30 の範囲で設定が可能です。省略時は 0 秒となります。フリーサイズ、固定サイズ、PDF のいずれのオプションでも有効です。
HeartRails Capture では画像 API の他に、GET メソッドで呼び出し、JSON 形式で結果を返す API を提供しています。
JSON API を使うことにより、サムネイル画像や PDF ファイルを直接作成したり、作成状況や対象ページのタイトルを取得することができます。
API の呼び出し方
API を呼び出すには、以下のようにメソッド名とパラメータを設定した URL を GET します。
http://capture.heartrails.com/api/{メソッド名}/{モード}/[{ディレイ}/]{コールバック}?{パラメータ}
* メソッド名: capture, get_status, is_done, etc...
* モード: free, tiny, small, medium, large, huge, pdf (省略時は small)
* ディレイ: delay=秒数 (省略可)
* コールバック: コールバック関数 (省略可)
* パラメータ: 対象 URL or ID
フリーサイズのサムネイル画像に対する操作にはモードとして free を、固定サイズや PDF に対する操作には対応するオプション名を指定します。
例えば、"http://www.mozilla-japan.org" のフリーサイズのサムネイル画像を作成したい場合、メソッド名として capture、モードに free、パラメータとして "http://www.mozilla-japan.org" を渡します。
http://capture.heartrails.com/api/capture/free/?http://www.mozilla-japan.org
パラメータの指定方法
パラメータには対象 URL そのものを指定する方法と、URL の代わりに ID を渡す方法があります。
URL の場合、一回の API 呼び出しにつき一つの URL の情報しか得られませんが、ID を渡す方法では複数の ID を指定して複数の URL の情報を一度に得ることができます。
例: http://capture.heartrails.com/api/get_title/?http://www.mozilla-japan.org
{"title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035}
例: http://capture.heartrails.com/api/get_title/?http://www.yahoo.co.jp
{"title":"Yahoo! JAPAN","id":54885}
例: http://capture.heartrails.com/api/get_title/?48035+54885
{"ids":[48035,54885],"titles":["Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird", "Yahoo! JAPAN"]}
API の出力ファイル
API の実行結果は UTF-8 エンコードの JSON 形式で返されます。
例: http://capture.heartrails.com/api/capture/free?http://www.mozilla-japan.org
{"status":"done","title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035}
コールバックを指定した場合は、JSON データをコールバック関数名で囲った文字列が返されます。
例: http://capture.heartrails.com/api/capture/free/cb[1]?http://www.mozilla-japan.org
cb[1]({"status":"done","title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035});
また、メソッド名を "メソッド名_sjis"、"メソッド名_euc" とすることで、S-JIS や EUC エンコードでの出力も可能です。
例: http://capture.heartrails.com/api/get_title_euc/free/?http://www.mozilla-japan.org
{"title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035}
※ EUC-JP エンコード
JSON API: capture
対象の URL に対するサムネイル、PDF を指定のモードで生成します。既に生成中、または生成されている場合は再生成は行いません。
例: http://capture.heartrails.com/api/capture/?http://www.mozilla-japan.org
{"status":"loading","title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035}
id: ID
status: ステータス ("start": 生成を開始, "loading": 生成中, "done": 生成済み, "error": それ以外)
title: タイトル
JSON API: force_capture
対象の URL に対するサムネイル、PDF を指定のモードで生成します。既に生成中、または生成されている場合でも再生成を行います。ただし、前回の生成から一時間以上経過していない場合は "error" となります。
例: http://capture.heartrails.com/api/force_capture/?http://www.mozilla-japan.org
{"status":"start","title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035}
id: ID
status: ステータス ("start": 生成を開始, "loading": 生成中, "done": 生成済み, "error": それ以外)
title: タイトル
JSON API: get_status
指定モードでの生成ステータスとタイトルを返します。
例: http://capture.heartrails.com/api/get_status/?http://www.mozilla-japan.org
{"status":"done","title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035}
id: ID
status: ステータス ("loading": 生成中, "done": 生成済み, "error": そのいずれでもない)
title: タイトル
例: http://capture.heartrails.com/api/get_status/?48035+54885
{"ids":[48035,54885],"statuses":["done","error"],"titles":["Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird", "Yahoo! JAPAN"]}
ids: ID の配列
statues: ステータスの配列
titles: タイトルの配列
JSON API: is_done
指定モードで生成済みかどうかを返します。
例: http://capture.heartrails.com/api/is_done/?http://www.mozilla-japan.org
{"result":true,"id":48035}
id: ID
result: 生成済みかどうか (true or false)
例: http://capture.heartrails.com/api/is_done/?48035+54885
{"results":[true,true],"ids":[48035,54885]}
ids: ID の配列
results: 生成済みかどうか (true or false) の配列
JSON API: is_loading
指定モードで生成中かどうかを返します。
例: http://capture.heartrails.com/api/is_loading/?http://www.mozilla-japan.org
{"result":false,"id":48035}
id: ID
result: 生成中かどうか (true or false)
例: http://capture.heartrails.com/api/is_loading/?48035+54885
{"results":[false,false],"ids":[48035,54885]}
ids: ID の配列
results: 生成中かどうか (true or false) の配列
JSON API: get_title
タイトルを返します。
例: http://capture.heartrails.com/api/get_title/?http://www.mozilla-japan.org
{"title":"Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird","id":48035}
id: ID
title: タイトル
例: http://capture.heartrails.com/api/get_title/?48035+54885
{"ids":[48035,54885],"titles":["Mozilla Japan ― 次世代ブラウザ Firefox とメールソフト Thunderbird", "Yahoo! JAPAN"]}
ids: ID の配列
titles: タイトルの配列
JSON API: get_id
ID を返します。
例: http://capture.heartrails.com/api/get_id/?http://www.mozilla-japan.org
