まずは、foursquare デベロッパーサイトよりアプリケーション登録をしましょう。
ここで発行される CLIENT ID、CLIENT SECRET を使ってfoursquare APIにアクセスできます。
概要
APIリクエスト
認証の有無によってリクエストパラメータが変わってきます。また、認証ありの場合、そのユーザに最適化された結果が返ってくるようになります。
認証あり
※最初に CLIENT ID、CLIENT SECRET で認証を行い、 oauth_token を発行しておきます。→認証手順
https://api.foursquare.com/v2/hoge/fuga
?param1=value1
¶m2=value2
&oauth_token=YOUR_OAUTH_TOKEN
&v=YYYYMMDD
認証なし
https://api.foursquare.com/v2/hoge/fuga
?param1=value1
¶m2=value2
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&v=YYYYMMDD
バージョニング
すべてのリクエストには v=YYYYMMDD が必要です。foursquare APIは YYYYMMDD に指定した日付時点の仕様で動作します。例えば、v=20140208 を指定しておけば、2014年2月9日にfoursquare側で大幅な仕様変更があった場合も、2014年2月8日時点での仕様で動作し続けるため、突然アプリケーションが動かなくなった！ということを防げます。
国際化
例えば、foursquareのカテゴリ一覧を取得する場合、日本語環境では 水族館 、英語環境では Aquariums といった具合に、ユーザの環境に適した表記が使用されます。これは、APIリクエスト時の HTTP ヘッダ Accept-Language によって変わってきます。通常はこれで問題無いと思いますが、locale=XX パラメータを使って強制的に言語を指定することも可能です。現在は、en, es, fr, de, it, ja, th, tr, ko, ru, pt, id がサポートされています。
回数制限
認証の有無、APIの種類によって変わってきます。
認証なしで使う場合
- venues/ から始まるAPI（venues/search, venues/explore等）は、ひとつのアプリケーションにつき、 1時間あたり合計5,000回まで
- それ以外のAPIはひとつのアプリケーションにつき、 1時間あたり合計500回まで
- 上の2種類は別々にカウントされるので、例えば venues/search を5,000回使ってしまった場合でも、tips/ APIを使うことはできる
認証ありで使う場合
- ひとつのOAuth Tokenにつき、 1時間あたり合計500回まで
残り回数
残りの使用可能回数は、APIレスポンスの X-RateLimit-Remaining と X-RateLimit-Limit で確認できます。
これで足りない場合は、foursquare に連絡することでリミットを上げてくれるようです。
エンドポイント
ベニュー検索
緯度経度 または 地域名 からベニューリストを検索します。認証不要ですが、認証ありの場合はそのユーザ向けにパーソナライズされた結果が返ってきます。
- HTTPメソッド：GET
- 認証：不要
パラメータ
| キー | 例 | 必須 | 解説 |
|---|---|---|---|
| ll | 44.3,37.2 | ○ | 緯度経度をカンマ区切りで指定。 |
| query | apple | 検索ワードを指定。 | |
| limit | 10 | 結果件数を指定。最大50まで。 | |
| intent | checkin | 検索の意図を指定。ベニューの表示順や検索範囲に影響が出てくる。checkin （デフォルト）を指定すると、ユーザにチェックインされやすいベニュー順に結果が返ってくる。global を指定すると世界中のベニューが検索範囲になる。 |
|
| radius | 800 | 検索半径をメートルで指定。 | |
| categoryId | asad13242l,btbe24353m | 結果をカテゴリで絞り込みたい場合に使用。カテゴリ名ではなく、カテゴリIDを指定。 |
他にもいろいろ指定できます。
レスポンス
Compact Object 形式（簡易表示）で返ってきます。Compact Objectの場合、ベニュー名や住所などの情報は含まれますが、Tipsや写真などの詳細情報は含まれません。
| フィールド | 解説 |
|---|---|
| id | ユニークなベニューID（例えば秋葉原駅は 4b19f917f964a520abe623e3） |
| name | ベニュー名 |
| contact | Twitterアカウントや電話番号 |
| location | 住所や緯度経度 |
| categories | ベニューが所属するカテゴリ（複数ある場合やゼロの場合もある） |
| verified | ベニューのオーナーによって認証された情報かどうか |
| stats | 総チェックイン数、今までにチェックインしたユーザー数、投稿されたTipsの数 |
| hereNow | 今チェックインしているユーザ数。認証ありの場合は、チェックイン中のユーザがフレンドかどうかもわかる |
他にもいろいろな情報が取得できます。