http://groups.google.com/group/foursquare-api/web/api-documentation の和訳です。
著作権はforsquareにあります。forsquareには(まだ)許可を取っていません。問題があれば削除します。(If any problem, I will remove this translation.)
和訳は2010年5月18日に行われました。それ以降の変更は反映されていません。
日本語訳は正確でないことがある点に留意してください。日本語訳の不備に伴う不利益があったとしても訳者はその責を負いません。
以下の単語はfoursquareでの固有名詞のため、あえて訳していません。
Foursquare API は Foursquare プラットフォーム上にアプリケーションを作るための API です。開発者は Foursquare への 新しい check-in の方法を作ったり、Foursquare コミュニティで作られたデータを可視化するためにAPIを使うことができます。我々の API はまだ開発途中であり、我々はあなたたちのフィードバックと提案を期待しています。
下記の公開したメソッドに加えて、我々のフィードを使ってあなたの check-in 履歴を得ることができます。フィードは RSS, KML, iCal の三種類のフォーマットで得られます。より詳しくは feeds.foursquare.com を見てください。
この API の使用には 規約 を遵守する必要があります。
ほとんどのメソッドには、Basic 認証か OAuth 認証が要求されます。 我々は、OAuth を推奨します。OAuthを使えば、クライアント(訳注: API を使って作るツールだと思われる)はユーザ名とパスワードを保持することなく、特別なトークンを使ってユーザの代わりに情報の要求を始められます。
Basic 認証を使うには、 credentials(電話番号とパスワード) を HTTP ヘッダに埋め込んで送る必要があります。ここにコマンドラインから curl を使う例を示します。
curl -u PHONE_OR_EMAIL:PASSWORD http://api.foursquare.com/v1/user
OAuth を使うには、 OAuth Howto を読んでください。
現在、リクエストへの応答は XML と JSON で得られます。XML が標準の形式です。URLは下記の形式にする必要があります。
You can currently request output in XML (the default) as well as JSON.
http://api.foursquare.com/v1/user.json
以下のようにURLにフォーマットの拡張子を含めない場合、標準の形式であるXML で出力されます。
http://api.foursquare.com/v1/user
距離は常に メートル法 で返されます。
ベストプラクティスとして、リクエストには値がないパラメータをできるだけ取り除いてくださるようお願いします。例: “/v1/user?uid=” の代わりに”/v1/user?uid=33” を送ってください。
メソッドがGETを要求している時は、GETを使ってください。もしもPOSTを要求している時はPOSTを使ってください。そうでなければ、リクエストは拒否されます。
返答の中にある、 <lastname> などのいくつかの要素は、空であることがあります。我々は空になる例について、メソッドの説明に注釈を入れようとしています。
ユーザ名は今のところ、Twitterのユーザ名が使われます。ユーザ名をバックエンドDBのキーとして使うことは気をつけてください。ユーザがTwitterのユーザ名をなんらかの理由で変えた場合は、DBが壊れてしまう可能性があります。ユーザ名の代わりにuidを使ってください。
全ての緯度経度メソッドでは(/checkin, /checkins, /tips など)、以下の情報をパラメータとして渡してくださるようお願いします。
これにより、我々はもっと正確な場所を得ることができます。これら全ての値はメートル法にしてください。
現在、”cityid”という考え方はAPIからは排除されています。都市に関する全てのメソッド(/switchcity, /checkcity)はすでのもう使えません。アプリケーションは、代わりにgeolatとgeolongを渡して緯度経度メソッドを使うように作り直す必要があります。
ヘッダの User-Agent を他と識別可能なように一意に設定してください。”Mozilla” や “libwww-perl/5.808” といった標準の識別子は、使用回数制限によって、使用停止にされる可能性があります。
我々は、送られてきた全ての一意な User-Agent (に加えて、アプリケーション名、メジャー/マイナー番号、含まれている情報など)を記録しています。我々がアプリケーションを一意に識別しやすくするために、User-Agentを構造化されたフォーマットで記述してくれるように強くお願いします。アプリケーション名、メジャーバージョン、マイナーバージョンに加えて他の識別可能な情報を、コロン”:”でつないでください。また、アプリケーションのバージョン番号を”:”の直後に置いてください。それ以降はログを取ったりデバグをするための情報など、好きな情報を含めて大丈夫です。
例: swipe-checkin:1.5 2009110501
例: Cool Square:4.0.0.247 Profile/MIDP-2.0 Configuration/CLDC-1.1 VendorID/105 Debug/Blackberry|9630|EMULATOR
このフォーマットに従うことで、我々はあなたのアプリケーションをもっと効率的に追跡することができます。我々はこれによって、自動的にアップグレードの紹介を行ったり、利用情報の統計を作成することができます。
APIの使用には、回数制限があります。この制限はあなたのアプリケーションが一時間に送るリクエストから計算されるMoving Windowに基づいています。
使用回数制限の初期値は一つのメソッドにつき一時間に200リクエストです。使用回数制限は以下の三つのうちの一つに適用されます。
あなたのアプリケーションでは、メソッドをうまく使う必要があります。例えば、可能な限りキャッシュするなどをしてください。/venue メソッドは他のメソッドに比べて長い間有効です。ヘッダのUser-Agentは一意に識別できる値を送ってください。我々はこれを利用回数を数えるのに使うかもしれません。
我々は使用回数制限の調整を行っています。もしもあなたのアプリケーションが制限にぶつかり、あなたがもっと大量にAPIを使いたいのならば、api@foursquare.comまでメールしてください。
friendが最近check-inしたリストを返します。
もし、 geolatとgeolongのペアを渡した場合(これはオプションですが、推奨です)、返答のそれぞれの<checkin>の中に<distance>が含まれます。
各<checkin>ブロックを解析するときにいくつか注意する必要があります。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<checkins>
<checkin>
<id>286939</id>
<user>
<id>467</id>
<firstname>Sarah</firstname>
<lastname>Simmons</lastname>
<photo>http://foursquare.com/userpix/467_1237171998.jpg</photo>
<gender>female</gender>
</user>
<venue>
<id>44379</id>
<name>Topshop</name>
<address>478 Broadway</address>
<crossstreet>at Broome</crossstreet>
<geolat>40.7215</geolat>
<geolong>-74.0001</geolong>
</venue>
<distance>2382</distance>
<display>Sarah S. @ Topshop</display>
<shout>Just tried on a dress ...</shout>
<created>Thu, 21 May 09 18:09:22 +0000</created>
</checkin>
ある場所にcheck-inします。
もし、その場所にmayorの情報がある場合は<mayor>ブロックが返されます。その場合、以下の情報が含まれている<type>ノードが返されます。
もしもこのcheck-inに関係するなにか特別な事があれば、<specials>ブロックが返されます。<specials>ノードは<special>という以下のタイプを持つサブノードを含みます。
もしもspecialが(venueの中ではなく)venueの近くの場合、<special>の代わりに近くのvenueを含む<venue>ノードが含まれます。
もしも、解除されたbadgeやtipsをインタラクティブに見せるインタフェースを作ろうとするならば、以下の例文を使うと、ユーザはなにが起こったのか簡単に理解することができます。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<checkin>
<message>OK! We've got you @ 4SQ HQ - Soho. This is your 8th checkin here!</message>
<id>413421</id>
<created>Mon, 29 Jun 09 14:21:06 +0000</created>
<venue>
<id>45506</id>
<name>4SQ HQ - Soho</name>
<address>...</address>
<crossstreet>btw Grand & Broome</crossstreet>
<city>New York</city>
<state>NY</state>
<zip>10013</zip>
...
</venue>
<mayor>
<type>nochange</type>
<checkins>10</checkins>
<user>
<id>138</id>
<firstname>Dan</firstname>
<lastname>M.</lastname>
<photo>http://playfoursquare.s3.amazonaws.com/userpix_thumbs/138_1237786934.jpg</photo>
<gender>male</gender>
</user>
<message>Dan M. is The Mayor of Bowery Wine Company.</message>
</mayor>
<badges>
<badge>
<id>123</id>
<name>Newbie</name>
<icon>http://foursquare.com/img/badge/newbie.png</icon>
<description>Congrats on your first checkin!</description>
</badge>
</badges>
<scoring>
<score>
<points>1</points>
<icon>http://foursquare.com/img/scoring/2.png</icon>
<message>First stop tonight</message>
</score>
<score>
<points>5</points>
<icon>http://foursquare.com/img/scoring/1.png</icon>
<message>First time @ 4SQ HQ!</message>
</score>
</scoring>
<specials>
<special>
<id>2</id>
<type>mayor</type>
<kind>nearby</kind>
<message>If you're the mayor, show the bartender and your first drink is free! (just beer and well drinks guys, let's be fair)</message>
<venue>
<id>333</id>
...
</venue>
</special>
</specials>
<checkin>
認証済みユーザに関するcheck-inのhistoryを返します。
以下に<checkin>ブロックを解釈するための注意を記します。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<checkins>
<checkin>
<id>947380</id>
<venue>
<id>34655</id>
<name>Monday Room</name>
<primarycategory>
<id>79156</id>
<fullpathname>Nightlife:Cocktails / Mixology</fullpathname>
<nodename>Cocktails / Mixology</nodename>
<iconurl>http://foursquare.com/img/categories/nightlife/cocktails.png</iconurl>
</primarycategory>
<address>201 Elizabeth St</address>
<crossstreet>btw Prince & Spring</crossstreet>
<city>New York</city>
<state>NY</state>
<zip>10012</zip>
<geolat>40.722</geolat>
<geolong>-73.9944</geolong>
<phone>2123437011</phone>
</venue>
<shout>drinks with brier</shout>
<created>Thu, 03 Sep 09 01:23:40 +0000</created>
</checkin>
<checkin>
<id>944792</id>
...
与えられたユーザのbadgeなどに関する情報を返します。もし、ユーザが最近check-inしたというデータ(つまり、そのユーザ自身あるいは認証済みユーザのfriendの場合)を持っている場合、その情報は<checkin>ブロックと同じように返されます。
もし要求されたユーザがそのユーザ自身(つまり、認証済みユーザ)である場合、初期設定が含まれる<settings>ブロックが返されます。この<settings>ブロックは、<sendtotwitter>や<sendtofacebook>などの属性に加えて、そのユーザのRSS/KMLのプライベートのfeed keyを含みます。sendtotwitterはcheck-in情報をtwitterに送るかどうかの初期設定であり、trueあるいはfalseが取りうる値です。sendtofacebookはcheck-in情報をfacebookのニュースfeedに送るかどうかの初期設定です。pingはユーザがクライアントアプリケーション(iphone, Android, Blackberry...)からのcheck-in通知を受け取るかを示します。取りうる値は、on(pingを送る)、off(pingを送らない)、goodnight(そのユーザの現在のタイムゾーンでAM 7時までpingを送らない)です。
もし指定されたユーザが認証済みユーザのfriendの場合、要求されたユーザの電話番号、email、twitter、Facebook IDの情報を得ることができます。加えて、get_pingsという情報も得られます。get_pingsはその認証済みユーザがfriend からのcheck-in通知を(push通知などで)受け取るかという情報です。get_pingsが取りうる値はtrueかfalseです。
<friendstatus>ノードは以下の4つの値のいずれかを取ります。
pendingyouとpendingthemは、アプリケーション上で状態を見せるのに役に立ちます。もし、「pendingyou」ならば、おそらく認証/拒絶の操作をユーザにさせるでしょう。もし「pending them」ならば、「認証待ち」と表示するでしょう。
ヒント: これはさらに、credentialを確認するのにも使えます。(ユーザがOAuth認証を無効にしていないか、あるいはベーシック認証でのログインが変更されていないか、確認してください)
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<user>
<id>33</id>
<firstname>Naveen</firstname>
<lastname>Selvadurai</lastname>
<photo>http://foursquare.com/userpix/33_1235974851.jpg</photo>
<gender>male</gender>
<phone>2129103995</phone>
<email>n@naveen.com</email>
<twitter>naveen</twitter>
<facebook>29103995</facebook>
<friendstatus>friend</friendstatus>
<checkin>
<id>413421</id>
<created>Mon, 29 Jun 09 14:21:06 +0000</created>
<venue>
<id>45506</id>
<name>4SQ HQ - Soho</name>
<address>...</address>
<crossstreet>btw Grand & Broome</crossstreet>
<city>New York</city>
<state>NY</state>
<zip>10013</zip>
...
</venue>
</checkin>
<badges>
<badge>
<name>Newbie</name>
<icon>http://foursquare.com/img/badge/newbie_on.png</icon>
<description>Congrats on your first check-in!</description></badge>
認証済みユーザ、つまり自分自身の場合(一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<user>
<id>33</id>
...
<settings>
<sendtotwitter>false</sendtotwitter>
<sendtofacebook>false</sendtofacebook>
<pings>on</pings>
</settings>
friendのリストを返します。もし、uidを指定しなかった場合、認証済みユーザのfriendリストが帰ります。もし、friendが許可しているのであれば、そのfriendのTwitterとFacebookアカウントも得られます。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<friends>
<user>
<id>32</id>
<firstname>Dennis</firstname>
<lastname>Crowley</lastname>
<photo>http://playfoursquare.s3.amazonaws.com/userpix_thumbs/32_1239135232.jpg</photo>
<gender>male</male>
<phone>2120000000</phone>
<email>dennis@crowley.co.uk</email>
<twitter>dens</twitter>
<facebook>803834</facebook>
</user>
..
</friends>
指定したあるいはキーワードに適合した場所に近いvenueのリストを返します。距離はメートル表記です。もし、認証しているのであれば、このメソッドはユーザとそのユーザのfriendに関係するメタデータも返します。認証されていない場合はこの情報は得られません。
<venue>ブロックの中のほとんどの情報は、オプションであることに注意してください。ユーザは住所、街、州といった情報がないvenueを作ることができます(そのvenueは緯度経度で指定されます)。アプリケーションは、このような状態にきちんと対処する必要があります。
<stats>ブロックには、そのvenueに関する回数の情報が入っています。<herenow>は、現在そこに何人いるかを示しています(この値は0に成り得ます)。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<venues>
<group type="Nearby favorites">
<venue>
<id>257</id>
<name>Bowery Ballroom</name>
<primarycategory>
<id>79167<id>
<fullpathname>Nightlife:Music Venue:Rock Club</fullpathname>
<nodename>Rock Club</nodename>
<iconurl>http://foursquare.com/img/categories/nightlife/default.png</iconurl>
</primarycategory>
<distance>10</distance>
<address>6 Delancey St</address>
<crossstreet>at Bowery</crossstreet>
<city>New York</city>
<state>NY</state>
<zip>10002</zip>
<geolat>40.7204</geolat>
<geolong>-73.9933</geolong>
<phone>2120000000</phone>
<twitter>BoweryBallroom</twitter>
<stats>
<herenow>36</herenow>
</stats>
</venue>
<venue>
<id>5055</id>
<name>Hiro Ballroom</name>
もし、venueの識別子(vid)が与えられたならば、mayorに関する情報、tips、to-do、tagsを含むvenueの情報を返します。もし与えられたvidがすでに他の”master” venueと合併されていた場合、返答にはエラーの代わりにその”master”venueの情報が含まれます。(訳注:”master”venueについてよく分かっていません)
もしもこのcheck-inに関係するなにか特別な事があれば、<specials>ブロックが返されます。<specials>ノードは<special>と以下のサブノードを含みます。
もし、specialが(現在見えているvenueの代わりに)近隣のvenueの場合、<kind>nearby</kind>と、<special>の中に<venue>ノードがあるはずです。これは近隣であることを強調しています。もし、現在ユーザが見ているvenueにspecialがあった場合、<venue>ブロックはなく、<kind>は”here”となります。
もしもユーザが認証されているならば、以下のメタデータも得られます。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<venue>
<id>49049</id>
<name>Pig & Whistle</name>
<primarycategory>
<id>79153</id>
<fullpathname>Nightlife:Bar</fullpathname>
<nodename>Bar</nodename>
<iconurl>http://foursquare.com/img/categories/nightlife/default.png</iconurl>
</primarycategory>
<address>365 Greenwich St</address>
<crossstreet></crossstreet>
<city>New York</city>
<state>NY</state>
<zip>10013</zip>
<phone>2120000000</phone>
<twitter>pignwhistle</twitter>
<geolat>40.7192</geolat>
<geolong>-74.0103</geolong>
<stats>
<checkins>828</checkins>
<herenow>15</herenow>
<beenhere>
<me>true</me>
<friends>true</friends>
</beenhere>
<mayor>
<user>
<id>134</id>
<firstname>Noah</firstname>
<lastname>Brier</lastname>
<photo>http://foursquare.com/userpix/134_1229036664.jpg</photo>
<gender>male</gender>
</user>
<count>2</count>
</mayor>
</stats>
<checkins>
<checkin>
<id>12345</id>
<created>Mon, 13 Apr 09 23:44:01 +0000</created>
<shout>deliciousness</shout>
<user>
<id>209</id>
<firstname>Harry</firstname>
<lastname>Heymann</lastname>
<photo>http://playfoursquare...</photo>
</user>
</checkin>
...
<tips>
<tip>
<id>6579</id>
<text>Don't miss the house-made salted hazelnut chocolate spread (perfected Nutella) for all the equally terrific truffles.</text>
<url>http://google.com/</url>
<created>Mon, 13 Apr 09 23:59:07 +0000</created>
<user>
<id>123</id>
<firstname>Sean</firstname>
<lastname>Good</lastname>
<photo>http://foursquare.com/userpix/9425_1238710251.jpg</photo>
<gender>male</gender>
</user>
</tip>
...
<tags>
<tag>lunch</tag>
<tag>pub</tag>
...
<specials>
<special>
<id>2</id>
<type>mayor</type>
<kind>nearby</kind>
<message>If you're the mayor, show the bartender and your first drink is free! (just beer and well drinks guys, let's be fair)</message>
<venue>
<id>333</id>
...
</venue>
</special>
</specials>
</venue>
現在サポートされている、カゴリーの階層リストを返します。
トップレベルのカテゴリーにはvenueを割り当てることができないため、IDを持たないことに注意してください。
クライアントアプリケーションを設計するときには、セッションごとに一回だけカテゴリーリストを取得するよう(そして短い間キャッシュするように)にしてください。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<categories>
<category>
<fullpathname>Arts & Entertainment</fullpathname>
<nodename>Arts & Entertainment</nodename>
<iconurl>http://foursquare.com/img/categories/arts_entertainment.png</iconurl>
<categories>
<category>
<id>78959</id>
<fullpathname>Arts & Entertainment:Arcade</fullpathname>
<nodename>Arcade</nodename>
<iconurl>http://foursquare.com/img/categories/arts_entertainment/arcade.png</iconurl>
</category>
<category>
<id>78960</id>
<fullpathname>Arts & Entertainment:Art Gallery</fullpathname>
<nodename>Art Gallery</nodename>
<iconurl>http://foursquare.com/img/categories/arts_entertainment/artgallery.png</iconurl>
</category>
...
venueを追加します。
もし、<error>が返ってきた場合、ユーザに入力の手直しをする方法を提供してください。加えてユーザに、「気にするな。いいからここにcheck-inする(never mind, check-in here anyway)」という、venueの名前だけで/v1/checkinを使って手動(「venueless」)でcheck-inする選択肢を与えてください。このようなケースはあまりないかもしれませんが、ユーザが重複したvenueを望んだ場合にはこのようなことが起きる場合があります。
全てのフィールドはオプションです。しかし、有効な住所あるいは緯度経度のどちらかを指定しなければなりません。どのような場合でも、緯度経度は与えてくれることをお願いします。
また、このvenueをカテゴリーに割り当てるために、category(primarycategoryid)を入れても構いません。/categoriesメソッドを使うことで、全カテゴリーのリストを得られます。venueの追加の時には、ユーザにカテゴリーの階層を見せ、適切なカテゴリーを選ぶようにしてくださるようお願いします。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<venue>
<id>49049</id>
<name>Pig & Whistle</name>
<primarycategory>
<id>79153</id>
<fullpathname>Nightlife:Bar</fullpathname>
<nodename>Bar</nodename>
<iconurl>http://foursquare.com/img/categories/nightlife/default.png</iconurl>
</primarycategory>
<address>365 Greenwich St</address>
<crossstreet></crossstreet>
<city>New York</city>
<state>NY</state>
<zip>10013</zip>
<phone></phone>
<geolat>40.7192</geolat>
<geolong>-74.0103</geolong>
<stats>
<checkins>0</checkins>
...
</stats>
<tips>
<tip>
...
</venue>
venueのflag/proposeを変更します。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<response>ok</response>
to-doアイテムとして、tipを付ける。(訳注: 説明が間違い？)
(Allows you to mark a tip as a to-do item)
返答:
<?xml version="1.0" encoding="UTF-8"?>
<response>ok</response>
指定したエリアの近くにあるtipsのリストを返します。(距離はメートル表記です)
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<tips>
<group type="Nearby">
<tip>
<id>8774</id>
<text>The burgers here are surprisingly delicious! Order one and wait out the ten minutes by having a pleasant conversation with Margaret.</text>
<distance>0</distance>
<created>Thu, 30 Apr 09 23:41:27 +0000</created>
<user>
<id>1818</id>
<firstname>Joe</firstname>
<lastname>LaPenna</lastname>
<photo>http://foursquare.com/userpix/1818_1239601037.jpg</photo>
<gender>male</gender>
</user>
<venue>
<id>36235</id>
<name>KK Cafe</name>
<address>252 Divisadero st</address>
<crossstreet>Haight</crossstreet>
</venue>
</tip>
venueに新しいtipやto-doを加えます。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<tip>
<id>16634</id>
<text>Get the hamburg doria (it's not on the menu)</text>
<created>Fri, 10 Jul 09 17:17:38 +0000</created>
</tip>
tipにto-doだという印を付けます。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<tip><id>94337</id><text>good selection of port.</text><created>Tue, 24 Nov 09 21:07:41 +0000</created></tip>
tipにdoneという印をつけます。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<tip><id>94337</id><text>good selection of port.</text><created>Tue, 24 Nov 09 21:07:41 +0000</created></tip>
tipの印を外します(以前の状態があれば、その状態に戻ります)。例えば、tipがto-doリストにあった場合、そのtipはto-doリストから外されます。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<tip><id>94337</id><text>good selection of port.</text><created>Tue, 24
Nov 09 21:07:41 +0000</created></tip>
認証待ちfriendのリストを取得します。つまり、他のユーザがあるユーザにfriend要求を行っており、そのユーザがまだ承認していないユーザのリストです。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<requests>
<user>
<id>16294</id>
<firstname>Benjamin</firstname>
<lastname>Bloom</lastname>
<photo>http://playfoursquare.s3.amazonaws.com/userpix_thumbs/16294_1254927789056.jpg</photo>
<gender>male</gender>
<twitter>bsbnyc</twitter>
<facebook>401256</facebook>
</user>
...
他のユーザから送られてきているfriend要求を承認します。成功した場合、<user>オブジェクトを返します。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<user>
<id>16294</id>
<firstname>...</firstname>
...
送られてきている、他のユーザからのfriendリクエストを拒否します。成功した場合、<user>オブジェクトを返します。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<user>
<id>16294</id>
<firstname>...</firstname>
...
他のユーザにfriendリクエストを送る。成功した場合、<user>オブジェクトを返します。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<user>
<id>16294</id>
<firstname>...</firstname>
...
自由記述の文字列が含まれている場合、適合する<user>のリストを返します。このメソッドは適合するユーザのうち、まだfriendでないユーザだけを返します。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<users>
<user>
<id>16294</id>
<firstname>...</firstname>
...
電話番号が綿された場合、適合する<user>オブジェクトのリストを返します。このメソッドはまだfriendになっていないユーザから適合するユーザを返します。渡す電話番号は一つだけでも構わないですし、カンマ”,”で区切った複数の電話番号を渡しても構いません。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<users>
<user>
<id>16294</id>
<firstname>...</firstname>
...
Twitterのユーザ名(Aとします)が渡されたとき、Twitter上でAのfriendであるユーザを<user>オブジェクトのリストとして返します。このメソッドはまだfriendになっていないユーザから適合するユーザを返します。
もし、Twitterのユーザ名が渡されてない場合、認証済みのユーザのTwitter名を使用します。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<users>
<user>
<id>16294</id>
<firstname>...</firstname>
...
個々のfriendやあなた自身に関する通知のオプションを変更します。friendはuidで識別されます。
返答:
<?xml version="1.0" encoding="UTF-8"?>
<settings>
<pings>on</pings>
</settings>
「ok」という文字列を返します。
返答 (一部省略):
<?xml version="1.0" encoding="UTF-8"?>
<response>ok</response>
状況によって、APIはエラーを返します。エラーは以下のカテゴリに分かれます。