foursquare apiについて
| 公式URL |
http://developer.foursquare.com/ http://developer.foursquare.com/docs/ 当サイトでは、「API V2」を扱います。 |
|---|---|
| 日本語訳 | http://www.tdoc.info/foursquare-API/ |
| 認証・制限など | OAuth。1時間に2000リクエスト。OAuthユーザ単位かIPアドレス単位。（2010/12/25時点） |
| 概要 | 位置情報マッピングサービス。 |
ここはなに？
foursquareの各種apiをコールしたときに、具体的にどんな値が返ってくるのか一瞬で分かります。
キーの意味を知るよりも、実際にどんな値が入っているかを知るほうが理解しやすいと思います。
目的の値を見つけて、あぁこの値を取り出すのはこのキーだな、とそんな使い方を想定しています。
foursquareの使い方
まずは、上のボタンからOAuth認証してください。（認証している場合は解除ボタンになります）
次は、このページの下にあるapiの一覧から目的っぽいページに移動しましょう。
パラメータをセットして、「call update」と書かれたボタンを押します。
百聞は一見にしかずです。 ユーザー情報に移動し、「call update」を押してみてください。
Users
ユーザー情報
ユーザーIDを指定して、詳細情報を取得します。
ユーザー検索
ユーザーのfriendを検索します。
パラメータはどれか１つ以上必須。
POSTだと、400エラーになる？(2010/12/25時点)
friendの承認待ち
friendの承認をまだ行っていないユーザーの一覧を取得します。
Badgeの情報
指定したユーザーのバッジの一覧を取得します。
Checkinの履歴
指定したユーザーチェックインの履歴を取得します。
■ 簡易ページング機能の実装について
limitとoffsetを使います。
offsetには、limitの倍数を指定します。
例えば、limitを10とした場合、offsetには、1ページ目は0。2ページ目は10。3ページ目は20と指定します。
計算式で表すと、offset = limit * (ページ番号 - 1) となります。
ページ最大値は、レスポンスに含まれる「response.checkins.count」からlimitで割り算して求められます。
但し、閲覧の途中で新しいcheckinが入ったときはズレていく問題があります。
多くの場合、無視すれば良いと思いますが、厳密なページングを実現するには、afterTimestampとbeforeTimestampを使います。
frinedの一覧
指定したユーザーのfrinedの一覧を取得します。
ユーザーのtips
指定したユーザーのtipsの一覧を取得します。
ユーザーのTODO
指定したユーザーのTODOの一覧を取得します。
※ recent 以外を指定する場合は、llの指定が必要です。
Venueの履歴
指定したユーザーが訪問したvenueの一覧を取得します。
friendの申請
指定したユーザーにfriendの申請を送ります。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
friendから外す
指定したユーザーのfriendを解除します。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
friendを承認する
指定したユーザーのfriend申請を承認します。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
friend申請を拒否する
指定したユーザーのfriend申請を拒否します。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
setpingsの設定
指定したユーザーがチェックインしたときに通知（ping）を受け取るかどうか指定します。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
Venues
Venueの詳細
VenueIDを指定して、Venue（スポット・お店など）の詳細情報を取得します。
Venueを追加
Venue（スポット・お店など）を作成します。
正しい住所か、緯度経度のいずれかは必須です。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
Venueのカテゴリ一覧
カテゴリの一覧を取得します。
最上位カテゴリは、venueに割り当てられないためIDはありません。
このApiの取得は頻繁にコールしないようにします。
例えばアプリケーション利用の開始に１回だけダウンロードし、キャッシュに保持しておきます。
ただし、カテゴリ一覧は更新されますので、１週間以上キャッシュしないようにする必要があります。
Venueを検索
指定した地点に近いvenueを検索します。
OAuthで取得すると、ユーザーとfriendの情報を含むことができます。
今Venueにいるユーザー
VenueIDを指定して、今Venue（スポット・お店など）にチェックインしているユーザーの一覧を取得します。
VenuesのTips
指定したVenueIDのTipsを取得します。
VenueをDodoに追加
指定したVenueIDをTODOとして印をつけます。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
間違いフラグを付ける
venueに間違いがあるときに、フラグをつけます。
「closed」フラグが承認された場合はそのvenueは検索結果に現れなくなります。
「mislocated」、「duplicate」の時は、モデレータは修正を試みます。
ユーザーが正しい住所を持っている(知っている)場合は、代わりに変更を提案を使ってください。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
変更を提案
venueの情報を変更する提案を行います。
提案したいvenueのVENUE_IDを指定し、提案したいパラメータをセットします。
変更の必要のないパラメータは省略します。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
Checkins
Checkinの詳細
CheckinIDを指定して、チェックインの詳細情報を取得します。
Checkinする
チェックインします。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
friendのCheckin一覧
friendが最近チェックインした場所の一覧を取得。
※ページング機能の実装（limit, offset）についてCheckinの履歴を参考にしてください。
Tips
Tipsの詳細
TipIDを指定して、Tipの詳細情報を取得します。
TODOとDoneを付けたtipsを含みます。
Tipsを追加
VenueIDを指定して、Tipsを追加します。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
Tipsを検索
近隣にあるTipsを検索します。
TODOのフラグを付ける
TipIDを指定して、TipにTODOのフラグをつけます。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
Done(完了)フラグを付ける
TipIDを指定して、Tipに完了のフラグをつけます。
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
フラグを外す
TipIDを指定して、TODOリストとDONEリストからTipのフラグを外します。
※本家ドキュメントのリクエストURLは誤っている？(2010/12/27)
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
Photos
写真の詳細
PhotoIDを指定して、写真の詳細情報を取得します。
写真を追加
PhotoIDを指定して、写真の詳細情報を取得します。
パラメータのすべてはオプションですが、checkinId, tipId, venueIdのいずれか１つは必須です。
TipsIDまたはVenuIDを指定した場合は、誰もが見られる公開状態となります。
CheckinIDを指定した場合は、Checkinの公開状態に従います。（twitterやfacebookを利用してcheckinした場合はこの限りではありません）
※私の理解が乏しいのかもしれませんが、アップする写真を指定するフィールドが本家ドキュメントに見当たりません。
Contenttypeをimage/jpegで送信するようにとはあるが、どうやって？
このApiの使い方をご存知の方は教えてください。(2010/12/27)
※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい？(2010/12/26)
