foursquare / Apiの概要

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を検索します。

パラメータはどれか1つ以上必須。

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の取得は頻繁にコールしないようにします。
例えばアプリケーション利用の開始に1回だけダウンロードし、キャッシュに保持しておきます。
ただし、カテゴリ一覧は更新されますので、1週間以上キャッシュしないようにする必要があります。

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のいずれか1つは必須です。

TipsIDまたはVenuIDを指定した場合は、誰もが見られる公開状態となります。
CheckinIDを指定した場合は、Checkinの公開状態に従います。(twitterやfacebookを利用してcheckinした場合はこの限りではありません)

※私の理解が乏しいのかもしれませんが、アップする写真を指定するフィールドが本家ドキュメントに見当たりません。
Contenttypeをimage/jpegで送信するようにとはあるが、どうやって? このApiの使い方をご存知の方は教えてください。(2010/12/27)

※ foursquareのPOST系はjsonpしても、ステータスコード200が返るとは限らないのでjavascriptからは厳しい?(2010/12/26)

Settings

設定の詳細

自身の設定情報を取得します。

※SETTING_ID は、特に意味のないように思われます。(2010/12/27)

設定を変更する

自身の設定情報を変更します。

※本家ドキュメントのSETTING_IDには、receiveCommentPingsが無いが抜けているものと思われます。(2010/12/27)

Multi

複数リクエストを一括送信

複数のApiをまとめてリクエストできます。
foursquareとの通信回数の削減に貢献します。