囲碁の棋譜を送るとその次の一手を考えて返すWeb API、「COSUMI API」の紹介です

1. 概要

COSUMI APIは、囲碁の棋譜を送るとその次の一手を考えて返すだけの、とてもシンプルなWeb APIです。GETもしくはPOSTでパラメータを送信すると、XML、JSON、もしくはJSONP形式でレスポンスを取得することができます。碁盤のサイズは、9路盤・11路盤・13路盤・15路盤のみに対応しています

現在のバージョン	COSUMI APIは停止しました
リクエストURL	http://www.cosumi.net/api/v1/
リクエスト HTTPメソッド	GET, POST
レスポンスの フォーマット	XML, JSON(JavaScript Object Notation), JSONP(JSON with Padding)
レスポンスの MIMEタイプ	XML - application/xml JSON - application/json JSONP - text/javascript
利用可能な 対局条件	碁盤のサイズは、9路盤・11路盤・13路盤・15路盤のみ利用可能です。COSUMI API自体は置き碁には対応していませんが、送信する棋譜にパスをうまく入れることによって、同じように考えさせることは可能です
制限事項	同一IPアドレスからのリクエストは、最低10秒間隔をあけてください。前回リクエスト時から10秒以内に再度リクエストを送るとエラーになります。また、サーバの負荷が高い時は、手を考えないでエラーレスポンスのみを返します
利用条件	免責事項に同意していただければ、商用利用を含めどなたでもご自由に利用いただけます

2. リクエスト

リクエストは、次のパラメータと共に送信します

パラメータ	説明
rf	レスポンスのフォーマット(Response Format)を指定します。指定できる値は xml、json、jsonp のみです。このパラメータが省略された場合は、XML形式でレスポンスを返します
cfn	レスポンスのフォーマットにJSONP形式を選択した時の、コールバック関数名(Callback Function Name)を指定します。指定できる値は、 アルファベット小文字(a-z)、アルファベット大文字(A-Z)、数字(0-9)、ピリオド(.)、アンダーバー(_)、ブラケット([])のみを含む、50文字以内の文字列 です。このパラメータが省略された場合は、 cosumi_callback が使用されます。JSONP以外のフォーマットが選択されている時は、このパラメータは無視されます
bs	碁盤のサイズ(Board Size)を指定します。指定できる値は 9、11、13、15 のみです。このパラメータが省略された場合は、9路盤と判断します
gr	棋譜(Game Record)を指定します。1手目から順に、横の座標と縦の座標をアルファベットの a から o を使って表した文字列を指定します。例えば、次のようなSGFファイルで表される棋譜があったとします (;GM[1]FF[4]SZ[9];B[de];W[ad];B[be];W[ef]) この棋譜をこのパラメータ用の値に変換すると deadbeef となります。パスは tt で表します。例えば、次のような棋譜があったとします (;GM[1]FF[4]SZ[9];B[de];W[ad];B[be];W[ef];B[]) この棋譜を変換すると deadbeeftt となります。パスが2回以上連続して続いた棋譜はエラーとなるので指定できません。また、指定可能な棋譜の最長手数は300手です。このパラメータが省略された場合は、まだ盤の上に石の置かれていない最初の局面と判断します

一般的なリクエストはこのような感じになります

http://www.cosumi.net/api/v1/?rf=xml&bs=9&gr=deadbeef

レスポンスのフォーマットがJSONP形式の場合は、パラメータ cfn でコールバック関数名を指定できます

http://www.cosumi.net/api/v1/?rf=jsonp&cfn=callback&bs=9&gr=deadbeef

すべてのパラメータは省略可能です。すべて省略すると9路盤の初手がXML形式で返されます

http://www.cosumi.net/api/v1/

実際にはありえない不正な棋譜を指定するとエラーになります

http://www.cosumi.net/api/v1/?gr=deadbeefdead

パスが2回以上連続して続いた棋譜もエラーになります

http://www.cosumi.net/api/v1/?gr=deadbeeftttt

3. レスポンス

レスポンスには status という項目のデータが必ず含まれます。この項目の値の意味は次のとおりです

値	意味
101	正常に処理されました
201	現在サーバの負荷が高いため、リクエストは拒否されました
202	前回リクエスト時からまだ10秒経過してないため、リクエストは拒否されました
203	リクエストパラメータが正しくないため、リクエストは拒否されました

status が 101 の場合は、合わせて move という項目のデータもレスポンスに含まれます。この項目がCOSUMI APIが考えた次の一手で、リクエスト時のパラメータ gr と同じく、2つの a から o のアルファベットがそれぞれ横と縦の座標を表します。 tt はパスを表します

XML形式での典型的なレスポンスは、次のようなものです

<?xml version="1.0"?>
<cosumi>
<status>101</status>
<move>de</move>
</cosumi> <?xml version="1.0"?>
<cosumi>
<status>201</status>
</cosumi>

JSON形式での典型的なレスポンスは、次のようなものです

{"status":"101","move":"de"} {"status":"201"}

JSONP形式での典型的なレスポンスは、次のようなものです

cosumi_callback({"status":"101","move":"de"}); cosumi_callback({"status":"201"});

4. 利用上の注意

COSUMI APIは、サーバの負荷が高い時には手を考えないでエラーレスポンスを返す仕様になっていますので、断続的に利用できたりできなかったりする時間帯が発生する場合があります。複数回のリクエストが必要となるサービス(対局など)に利用される場合は、どうかご注意ください

COSUMI APIは、事前の予告無く仕様の変更やAPIサービスの停止を行うことがあります。大幅に互換性が失われる大きな仕様変更は新しいリクエストURLで新規に公開する予定ですが、現在のAPIサービスに対しても仕様の変更や拡張がたびたび行われるものと考えてください。また、こちらの独断で特定のクライアントからのリクエストを制限することがあります

5. その他

Flashアプリケーションからも利用できるように、crossdomain.xmlファイルも用意しました

http://www.cosumi.net/api/crossdomain.xml

ルート直下に置かれたマスターポリシーファイル(http://www.cosumi.net/crossdomain.xml)では、外部ドメインからのアクセスを許可していませんので、ご注意ください

COSUMI APIの囲碁の棋力は、COSUMIの囲碁対局ゲームの時と比べ少し弱くなっています

6. 免責事項

COSUMI APIの利用により生じたいかなる損害についても、運営者は一切の責任を負いません

7. 更新履歴