Jaiku API 仕様書

公式の API 解説書 "Jaiku | Documentation" にしたがって実際に Jaiku に投稿試験をしてみたところ、常に投稿に失敗することが判明。 いろいろ調査した結果、どのように対処すれば投稿できるか判明したため、以下にまとめてみた。 なお、情報の取得に関する API は、(individual stream entry を除いて)公式の API 解説書通りで問題ない。

パーソナルキー

Jaiku の API のうち、認証の必要なもの(現時点では POST 系の API のみ)に関しては、パスワードの代わりに、各ユーザごとに割り当てられた personal_key を使用する。 personal_key は、Jaiku にログイン後、http://jaiku.com/api にアクセスすれば、 "Your API Key" のところに表示されているので、それを使うことになる。 もしくは、http://api.jaiku.com/keyにアクセスすれば、personal_key が表示されるので、それを使う。 この personal_key は他人に知られないように注意すること。

Presence の取得

public stream の取得

全ユーザを対象に、公開されている投稿内容を取得する(最新のものから最大20件)

• エンドポイントURL:
  • http://jaiku.com/feed/json
    (JSON 形式で取得)
  • http://jaiku.com/feed/rss
    (RSS 2.0 形式で取得)
  • http://jaiku.com/feed/atom
    (Atom 1.0 形式で取得)
• メソッド: GET
• 認証(パーソナルキー)は不要

user's stream の取得

指定ユーザを対象に、公開されている投稿内容を取得する(最新のものから最大20件)

• エンドポイントURL:
  • http://スクリーン名.jaiku.com/feed/json
    (JSON 形式で取得)
  • http://スクリーン名.jaiku.com/feed/rss
    (RSS 2.0 形式で取得)
  • http://スクリーン名.jaiku.com/feed/atom
    (Atom 1.0 形式で取得)
• メソッド: GET
• 認証(パーソナルキー)は不要

user information の取得

指定ユーザの contact 一覧を取得する (ただし、指定ユーザが情報を lock していない場合のみ取得できる)

• エンドポイントURL:
  • http://スクリーン名.jaiku.com/json
    (JSON 形式で取得)
• メソッド: GET
• 認証(パーソナルキー)は不要

user presence の取得

指定ユーザの presence (プロフィールと現在いる場所) を取得する (この API は、「(ブログ等に貼り付ける目的で用意されている)バッジ」で利用している)

• エンドポイントURL:
  • http://スクリーン名.jaiku.com/presence/json
    (JSON 形式で取得)
  • http://スクリーン名.jaiku.com/presence/xml
    (XML 形式で取得)
• メソッド: GET
• 認証(パーソナルキー)は不要

last stream entry の取得

指定ユーザの最新の発言(コメントが付いている場合はコメントも一緒に)を取得する

• エンドポイントURL:
  • http://スクリーン名.jaiku.com/presence/last/json
    (JSON 形式で取得)
  • http://スクリーン名.jaiku.com/presence/last/xml
    (XML 形式で取得)
• メソッド: GET
• 認証(パーソナルキー)は不要

individual stream entry

指定ユーザの指定アイテムに限定して、公開されている投稿内容を取得する(最新のものから最大20件)

• エンドポイントURL:
  • http://スクリーン名.jaiku.com/presence/アイテム名/json
    (JSON 形式で取得)
  • http://スクリーン名.jaiku.com/presence/アイテム名/atom
    (Atom 1.0 形式で取得)
• メソッド: GET
• 認証(パーソナルキー)は不要

「アイテム名」に指定できるものが不明。message, comment, music 等を指定してみたが、 いずれの場合も http://スクリーン名.jaiku.com/ (htmlファイル) が GET されてくるだけだった。 使い方が悪いだけだと思うが、正しい使い方が不明。

Presence の投稿

JSON バージョンと XML-RPC API バージョンの2種類がある。どちらを使っても構わない。

JSON バージョン

• エンドポイントURL: http://api.jaiku.com/json
• メソッド: POST
• リクエスト:
  user=スクリーン名&personal_key=パーソナルキー&method=presence.send&message=投稿内容&icon=アイコン番号
  (icon=アイコン番号 は省略可能。省略した場合は 300 を指定したものとみなされる)
  「投稿内容」は(URLエンコードする前の状態で)最大140バイト

訳者注: パラメータに誤りがある等の理由で投稿に失敗した場合(例えば、アイコン番号が間違っている場合)でも

{"status":"ok"}

が返ってくることがあるので注意。投稿実行後、"last stream entry" を取得して投稿に成功しているかどうか確認することを推奨する。

XML-RPC API バージョン

• エンドポイントURL: http://api.jaiku.com/xmlrpc
• メソッド: POST
• リクエスト:

  <?xml version="1.0" encoding="UTF-8"?>
  <methodCall>
    <methodName>presence.send</methodName>
    <params>
      <param>
        <value>
          <struct>
            <member>
              <name>user</name>
              <value><string>スクリーン名</string></value>
            </member>
            <member>
              <name>personal_key</name>
              <value><string>パーソナルキー</string></value>
            </member>
            <member>
              <name>generated</name>
              <value><boolean>0 または 1</boolean></value>
            </member>
            <member>
              <name>message</name>
              <value><string>投稿内容</string></value>
            </member>
            <member>
              <name>icon</name>
              <value><int>アイコン番号</int></value>
            </member>
            <member>
              <name>location</name>
              <value>
                <struct>
                  <member>
                    <name>neighbourhood</name>
                    <value>地域名</value>
                  </member>
                  <member>
                    <name>city</name>
                    <value>都市名</value>
                  </member>
                  <member>
                    <name>country</name>
                    <value>国名</value>
                  </member>
              </value>
            </member>
          </struct>
        </value>
      </param>
    </params>
  </methodCall>
  

  • user: 必須
  • personal_key: 必須
  • generated: 省略可能。省略した場合は、0 (FALSE) を指定したものとみなす。なお、1 (TRUE) のとき、はてなダイアリーでいうところの「ちょっとした更新」であることを指示する。
  • message: 必須。最大140バイトまで
  • icon: 省略可能。省略した場合は 300 (Blank) を指定したものとみなす
  • location: 省略可能。省略した場合は、「居住地」(Space)で設定した情報を指定したものとみなす。
    また、省略した場合は、投稿実行後、http://jaiku.com/ の右サイドバーに表示される Location が空白状態になる(ログイン状態で閲覧時)。
    なお、location を指定する場合は、必ず country を指定すること。city と neighbourhood は省略しても構わない(ただし、neighbourhood 指定時は city も指定すること)。
    あるいは、以下のような簡易表記も使用可能である。

              <member>
                <name>location</name>
                <value>
                  <struct>
                    <member>
                      <name>whatever</name>
                      <value>[[地域名,] 都市名,] 国名</value>
                    </member>
                </value>
              </member>
    

訳者注: 投稿に成功した場合は、XML 形式のテキストが返ってくる。それ以外のテキスト(プレーンテキストあるいは html 形式のテキスト)が返ってきた場合は、投稿に失敗している。 以下に、応答例を示す。

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value>
        <array><data>
</data></array>
      </value>
    </param>
  </params>
</methodResponse>

アイコン番号

以下の表に示すアイコンのうち、available が yes のもののみ、指定可能。available が no のものを指定した場合は、投稿に失敗する。 (available が no のものを指定した場合でも、JSON バージョンの場合は、投稿に成功したことを示すレスポンスが返ってくるが、実際には投稿に失敗している)

code	item	image	available
300	Blank		yes
301	car	-> 401	no
302	alarmclock		no
303	loudspeaker		yes
304	tram		yes
305	casette		no
306	underware		no
307	rollerblade		no
308	uzi		yes
309	scoop		no
310	bomb		yes
311	bra		no
312	videotape		no
313	cigarettes		no
314	vinyl		no
315	champaign		no
316	airplain		yes
317	bus		yes
318	grumpy		yes
319	coffee		yes
320	camera		no
321	basketball		no
322	beer		yes
323	binoculars		yes
324	boiler		no
325	walk		yes
326	wallclock		yes
327	trashcan		no
328	tv		yes
329	computing		yes
330	videocamera		no
331	game		yes
332	cone		no
333	driller		yes
334	popcorn		no
335	playshirt		no
336	disc		no
337	event		no
338	exclamationmark		no
339	football		yes
340	footballshoe		no
341	eat		yes
342	gameboy		no
343	grenade		no
344	hand		no
345	hanger		no
346	hearingprotector		yes
347	love		yes
348	balloons		yes
349	clock		no
350	barrier		no
351	laptop		no
352	megaphone		yes
353	microwave		no
354	book		yes
355	middlefinger		no
356	notes		no
357	question		no
358	rollator		yes
359	shuttlecock		no
360	salt		no
361	scull		yes
362	sk8		no
363	sleep		yes
364	snorkeling		yes
365	snowflake		no
366	soda		no
367	song		yes
368	spraycan		yes
369	sticks		no
370	storm		yes
371	straitjacket		yes
372	metro		yes
373	luggage		yes
374	sun		no
375	taxi		yes
376	technics		no
377	toaster		yes
378	train		yes
379	wheelchair		no
380	zippo		no
381	icecream		yes
382	movie		no
383	makeup		yes
384	bandaid		no
385	wine		no
386	clean		no
387	blading		yes
388	bike		yes
389	pils		yes
390	picnic		no
391	lifejacket		yes
392	home		yes
393	happy		yes
394	toiletpaper		yes
395	theatre		yes
396	shop		yes
397	search		no
398	cloudy		no
399	hurry		yes
400	morning		yes
401	car		yes
402	baby-boy		no
403	baby-girl		no

補足

Jaiku には Twitter の friends_timeline に相当する情報(Jaiku では overview と称する)を取得する API が存在しないため、 friends_timeline 相当の情報を得るには、以下のような方法を使う。

1. まず、自分の「user's stream の取得」を実行する
2. 次に、自分の「user information の取得」を実行し、コンタクト一覧を保存する(キャッシュしておくとよい)
3. 全コンタクト(Twitter の friends 相当)に対して、「user's stream の取得」を実行する
4. 各 user's stream の内容をマージし、時系列順にソートする

コンタクトの数が多ければ多いほど処理コストが高くなるので、更新頻度の低いユーザの stream の取得頻度は減らす等の工夫が必要かもしれない。

関連ページ

• Twitter クライアント chirrup 1.12版 ― Jaiku にも対応してみました
• Jaiku API 仕様書 (勝手に日本語訳シリーズ)
• Twitter API 仕様書 (勝手に日本語訳シリーズ) 改訂版
• Twitter の API に関するメモ