API 日本語ガイド

smart.fm デベロッパーサイトへようこそ

smart.fm デベロッパーサイトでは、smart.fm APIを利用する開発者向けのテクニカルリソースとコミュニティを用意しています。

• smart.fm API入門 - このドキュメント
• API リファレンス - http://developer.smart.fm/docs
• API デベロッパアカウントの登録 - Registration このドキュメントに日本語での補足説明があります
• アプリケーションの登録と API キーの取得 - Application このドキュメントに日本語での補足説明があります
• デベロッパーズフォーラム - iKnow! Developers Forums

また特に日本のデベロッパの方々に向けて、以下の Q&A ページを用意しています。

• API 全般に関する Q&A（日本語）
• API コンテスト「iKnow! API KICK OFF!」に関する Q&A

smart.fm API 入門

はじめに

smart.fm API は、一般的な REST アーキテクチャーに基づいて規定されています。またレスポンスのフォーマットとしては XML のほか JSON による情報取得も可能です。これらの技術を利用し、smart.fm サイトの豊富な情報を、データフィードというかたちで受信することが可能です。API Key での認証を行えば、smart.fm サイトへのデータ登録も行えます。

HTTP リクエスト

smart.fm API のベース URL は以下の通りです。

http://api.smart.fm/

study_list の Feed 呼び出し例

http://api.smart.fm/lists/9900/items.xml

その他各種リクエストの詳細については、API Documents (http://developer.smart.fm/docs) をご参照ください。

レスポンス

レスポンスのフォーマットとして、現在 XML, HTML, RSS, JSON に対応しています。（注：API によっては、対応していないデータ形式もあります）

JSON ではコールバックに対応していますので、以下のような呼び出しで利用できます。

http://api.smart.fm/lists/9900/items.json?callback=update_my_widget

API によってデータ構造は変わりますが、XML での学習コンテンツについては XMLVocabulary 仕様に準拠しています。また JSON では XMLVocabulary をシリアライゼーションしたものを利用しています。レスポンスの詳細については、API Documents (http://developer.smart.fm/docs) をご参照ください。

API キーを使った呼び出し

下記の例のように、リクエストに api_key パラメータを付加して呼び出します。

http://api.smart.fm/items/extract.xml?api_key=d6bu49h84yj85z2mgnbh5t4j&text=I

例外処理

サーバが正常なレスポンスが返せない場合は、エラー情報として HTTP のステータスコードを XML 文書として送信します。

サーバが 403 Access Denied を返した場合のレスポンス例

<?xml version="1.0"?>
<error code="403" message="Access Denied"/>

HTTP レスポンス自体は、例外があった場合でも HTTP 200 OK を返しますので、クライアント側での例外処理が必要となります。

JSON でのレスポンス例

{:error => {:code => 403, :message => 'Access Denied'}}

XMLVocabulary仕様

※ご注意：この仕様は現在策定途中のもので、予告無く変更される可能性があります。

XMLVocabulary フォーマットは、ある語彙を学習する目的を持ったコンテンツを表現します。このフォーマットの構成は、語彙そのものを表すキュー(cue)とその意味、解釈を表すレスポンス(response)から成り立っています。キュー、レスポンスの構造の中には学習をサポートするためのイメージ、サウンド、例文（センテンス）といったコンテンツ情報が付随します。

このドラフト仕様では以下のフォーマットを規定しています

  アイテムのキュー　
  アイテムのレスポンス
  アイテムの例文（センテンス）
  その他のメディアデータ

XML文書によるボキャブラリデータの例です。（データを見やすくするためにCDATAセクションを除外しています）。

http://api.smart.fm/users/xaky/items.xml

<vocabulary xsi:schemaLocation="http://www.iknow.co.jp/api/specifications/vocabulary/1.0" version="1.0">
<items>
<item id="435852">
    <cue part_of_speech="Verb">
        <text>みる</text>
        <sound>
             http://media4.cerego.co.jp/contents/JLL/audio/JW09011A.mp3
        </sound>
    </cue>
    <response>
        <text>see, look at</text>
    </response>
    <sentences>
        <sentence id="246959">
            <text>私は絵を<b>見る</b>のが好きです。</text>
            <native_transliteration>わたし は え を <b>みる</b> の が すき です</native_transliteration>
            <romanized_transliteration>watashi ha e wo <b>miru</b> no ga suki desu</romanized_transliteration>
            <translation>I like looking at pictures.</translation>
        <sound>
                http://media4.cerego.co.jp/contents/JLL/audio/JS09011A.mp3
            </sound>
        <image>
                http://media4.cerego.co.jp/contents/images/3336455.jpg
            </image>
            <editor>Cerego</editor>
            <attribution_source>Cerego</attribution_source>
        </sentence>
    </sentences>
</item>
<item id="67989">
    <cue part_of_speech="Noun">
        <text>lactobacillus</text>
    <sound>
            http://media4.cerego.co.jp/contents/halpern/en_male/E0070535.mp3
        </sound>
    </cue>
    <response>
        <text>乳酸桿菌</text>
    </response>
    <sentences/>
</item>
</items>
</vocabulary>

サンプル

Google ガジェットを利用した簡単なサンプルをご利用いただけます

HTMLソース

<script src="http://www.gmodules.com/ig/ifr?url=http://hosting.gmodules.com/ig/gadgets/file/118191294908615782533/iknow_xaky_item_demo02.xml&amp;synd=open&amp;w=320&amp;h=200&amp;title=iKnow+Gadget&amp;border=http%3A%2F%2Fwww.gmodules.com%2Fig%2Fimages%2F&amp;output=js"></script>

ガジェットのソースコード

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="iKnow Gadget" scrolling="true">
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
function init() {
var feedUrl = 'http://api.dev.iknow.co.jp/users/xaky/items.xml';
_IG_FetchXmlContent(feedUrl, function (res) {
if (res == null
|| typeof(res) != "object"
|| res.firstChild == null) {
_gel('out').innerHTML = "object is null";
return;
}
var itemList = res.getElementsByTagName("item");
var html ="<div><ul>";
for (var i = 0; i < itemList.length ; i++) {
var nodeList = itemList.item(i).childNodes;
var id = itemList.item(i).getAttribute("id");
for (var j = 0; j < nodeList.length ; j++) {
var node = nodeList.item(j);
if (node.nodeName == "cue") {
var title = node.firstChild.firstChild.nodeValue;
}
if (node.nodeName == "responses") {
var resp = node.firstChild.firstChild.firstChild.nodeValue;
}
}
html += '<li><a href="http://www.iknow.co.jp/item/' + id +'" target="_blank">'+ title + '(' + resp + ')' + '</a></li>';
}
html += '</ul></div>';
_gel('out').innerHTML = html;
});
}
_IG_RegisterOnloadHandler(init);
</script>
<style type="text/css">
<!--
body {
font-size: 76%;
}
div#out p {
text-align:center;
margin: 2px;
}
ul {
list-style-type: circle;
margin: 2px;
padding: 5px 0 5px 12px;
}
li {
margin: 2px;
}
-->
</style>
<div id="out"></div>
]]>
</Content>
</Module>

<?xml version="1.0" encoding="UTF-8"?>
<Module>
<ModulePrefs title="iKnow Gadget" scrolling="true">
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
function init() {
var feedUrl = 'http://api.iknow.co.jp/users/xaky/items.xml';
_IG_FetchXmlContent(feedUrl, function (res) {
if (res == null
|| typeof(res) != "object"
|| res.firstChild == null) {
_gel('out').innerHTML = "object is null";
return;
}
var itemList = res.getElementsByTagName("item");
var html ="<div><ul>";
for (var i = 0; i < itemList.length ; i++) {
var nodeList = itemList.item(i).childNodes;
var id = itemList.item(i).getAttribute("id");
for (var j = 0; j < nodeList.length ; j++) {
var node = nodeList.item(j);
if (node.nodeName == "cue") {
var title = node.firstChild.firstChild.nodeValue;
}
if (node.nodeName == "response") {
var resp = node.firstChild.firstChild.nodeValue;
}
}
html += '<li><a href="http://www.iknow.co.jp/item/' + id +'" target="_blank">'+ title + '(' + resp + ')' + '</a></li>';
}
html += '</ul></div>';
_gel('out').innerHTML = html;
});
}
_IG_RegisterOnloadHandler(init);
</script>
<style type="text/css">
<!--
body {
font-size: 76%;
}
div#out p {
text-align:center;
margin: 2px;
}
ul {
list-style-type: circle;
margin: 2px;
padding: 5px 0 5px 12px;
}
li {
margin: 2px;
}
-->
</style>
<div id="out"></div>
]]>
</Content>
</Module>

<?xml version="1.0" encoding="UTF-8"?>
    <Module>
        <ModulePrefs title="iKnow Gadget" scrolling="true">
        </ModulePrefs>
        <Content type="html">
        <![CDATA[
            <script type="text/javascript">
                function init() {
                    var feedUrl = 'http://api.iknow.co.jp/users/xaky/items.xml';
                        _IG_FetchXmlContent(feedUrl, function (res) {
                            if (res == null
                                || typeof(res) != "object"
                                || res.firstChild == null) {
                                _gel('out').innerHTML = "object is null";
                                return;
                            }
                        var itemList = res.getElementsByTagName("item");
                        var html ="<div><ul>";
                        for (var i = 0; i < itemList.length ; i++) {
                            var nodeList = itemList.item(i).childNodes;
                            var id = itemList.item(i).getAttribute("id");
                            for (var j = 0; j < nodeList.length ; j++) {
                                var node = nodeList.item(j);
                                if (node.nodeName == "cue") {
                                    var title = node.firstChild.firstChild.nodeValue;
                                }
                                if (node.nodeName == "response") {
                                    var resp = node.firstChild.firstChild.nodeValue;
                                }
                            }
                            html += '<li><a href="http://www.iknow.co.jp/item/' + id +'" target="_blank">'+ title + '(' + resp + ')' + '</a></li>';
                        }
                        html += '</ul></div>';
                        _gel('out').innerHTML = html;
                    });
                }
                _IG_RegisterOnloadHandler(init);
                </script>
            <style type="text/css">
            <!--
            body {
                font-size: 76%;
            }
            div#out p {
                text-align:center;
                margin: 2px;
            }
            ul {
                list-style-type: circle;
                margin: 2px;
                padding: 5px 0 5px 12px;
            }
            li {
                margin: 2px;
            }
    -->
        </style>
        <div id="out"></div>
        ]]>
    </Content>
</Module>

※google ガジェットについては下記のサイトをご参照下さい

http://igooglecon.jp/chapter03/index.html

参考リンク

smart.fm APIを利用する場合、APIサイトと通信するためのHTTP処理と、XMLなどのレスポンスのフォーマットを開発に利用する言語のデータ形式に変換するためのパース処理が必要となります。以下に主要な開発言語で利用されているライブラリを紹介します。

HTTPリクエスト

Javascript XMLHttpRequest
JAVA HttpClient HttpURLConnection
C# System.Web.HTTPWebRequest
PHP libcurl
Perl LWP
Ruby rest-open-uri net/http
Python httplib2

パーサ

XML/RSS

Javascript responseXML
JAVA java.xml
C# System.Xml.XmlReader
PHP xml_parser_create
Ruby REXML
Python　ElementTree

JSON

http://www.json.org/json-ja.html

参考文献：Leonard Richardson,Sam Ruby「RESTful Webサービス」 オライリー・ジャパン 29ページ
：Billy Hoffman,Bryan Sullivan「Ajax セキュリティ」毎日コミュニケーションズ 124ページ

セキュリティ制限のあるクライアントでのHTTP通信について

利用するプラットフォームや、HTTPライブラリによっては、セキュリティの観点からローカルサーバ以外へのリクエスト（クロスサイトリクエスト）を禁止している場合があります（プログラムの置かれる開発者のサイトから、smart.fm APIサイトへの通信を禁止しており、セキュリティエラーなどが発生し、通信が行えない等）。
上記の問題は、ローカルサーバにクロスサイトリクエスト制限の無いスクリプト等を設置し、プログラムはそのスクリプトを経由してsmart.fm APIサイトへアクセスすることで回避できます。

PHP-cURLを利用した例

<?php
$s = "http://api.iknow.co.jp/users/xaky/items.xml";//またはプログラムからのパラメータ（$_GET["パラメータ名"]など）
$cURL_handle = curl_init($s);
curl_setopt($cURL_handle, CURLOPT_HEADER, 0);
$data = curl_exec($cURL_handle);
curl_close($cURL_handle);
?>

APIデベロッパアカウントの登録

こちらで登録が行えます。
登録方法については下記をご参照ください(クリックで拡大します)。

アプリケーションの登録と API キーの取得

こちらで登録が行えます。
登録方法については下記をご参照ください。