foursquare APIでできること



まずは、foursquare デベロッパーサイトよりアプリケーション登録をしましょう。

* [foursquareアプリケーションの登録](http://qiita.com/koogawa/items/2e1e1c2c0fd9ca33ea6e)

ここで発行される `CLIENT ID`、`CLIENT SECRET` を使ってfoursquare APIにアクセスできます。

# 概要

## APIリクエスト

認証の有無によってリクエストパラメータが変わってきます。また、認証ありの場合、そのユーザに最適化された結果が返ってくるようになります。

### 認証あり

※最初に `CLIENT ID`、`CLIENT SECRET` で認証を行い、 `oauth_token` を発行しておきます。→[認証手順](https://developer.foursquare.com/overview/auth)

```
https://api.foursquare.com/v2/hoge/fuga
?param1=value1
&param2=value2
&oauth_token=YOUR_OAUTH_TOKEN
&v=YYYYMMDD
```

### 認証なし

```
https://api.foursquare.com/v2/hoge/fuga
?param1=value1
&param2=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日時点での仕様で動作し続けるため、突然アプリケーションが動かなくなった！ということを防げます。

* [https://developer.foursquare.com/overview/versioning](https://developer.foursquare.com/overview/versioning)

## 国際化

例えば、foursquareのカテゴリ一覧を取得する場合、日本語環境では __水族館__ 、英語環境では __Aquariums__ といった具合に、ユーザの環境に適した表記が使用されます。これは、APIリクエスト時の HTTP ヘッダ `Accept-Language` によって変わってきます。通常はこれで問題無いと思いますが、`locale=XX` パラメータを使って強制的に言語を指定することも可能です。現在は、en, es, fr, de, it, ja, th, tr, ko, ru, pt, id がサポートされています。

* https://developer.foursquare.com/overview/versioning#internationalization

## 回数制限

認証の有無、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 に連絡することでリミットを上げてくれるようです。

* https://developer.foursquare.com/overview/ratelimits

# エンドポイント

## ベニュー検索

https://api.foursquare.com/v2/venues/search

__緯度経度__ または __地域名__ からベニューリストを検索します。認証不要ですが、認証ありの場合はそのユーザ向けにパーソナライズされた結果が返ってきます。

* HTTPメソッド：GET
* 認証：不要

### パラメータ

| キー | 例 | 必須 | 解説 |
|:--|:--|:--:|:--|
| ll | 44.3,37.2 | ○ | 緯度経度をカンマ区切りで指定。 |
| query | apple |  | 検索ワードを指定。 |
| limit | 10 |  | 結果件数を指定。最大50まで。 |
| intent | checkin |  | 検索の意図を指定。ベニューの表示順や検索範囲に影響が出てくる。`checkin` （デフォルト）を指定すると、ユーザにチェックインされやすいベニュー順に結果が返ってくる。`global` を指定すると世界中のベニューが検索範囲になる。|
| radius | 800 |  | 検索半径をメートルで指定。 |
| categoryId | asad13242l,btbe24353m |  | 結果をカテゴリで絞り込みたい場合に使用。カテゴリ名ではなく、カテゴリIDを指定。 |

他にもいろいろ指定できます。

* https://developer.foursquare.com/docs/venues/search

### レスポンス

__Compact Object__ 形式（簡易表示）で返ってきます。Compact Objectの場合、ベニュー名や住所などの情報は含まれますが、Tipsや写真などの詳細情報は含まれません。

| フィールド | 解説 |
|:--|:--|
| id | ユニークなベニューID（例えば秋葉原駅は 4b19f917f964a520abe623e3） |
| name | ベニュー名 |
| contact | Twitterアカウントや電話番号 |
| location | 住所や緯度経度 |
| categories | ベニューが所属するカテゴリ（複数ある場合やゼロの場合もある） |
| verified | ベニューのオーナーによって認証された情報かどうか |
| stats | 総チェックイン数、今までにチェックインしたユーザー数、投稿されたTipsの数 |
| hereNow | 今チェックインしているユーザ数。認証ありの場合は、チェックイン中のユーザがフレンドかどうかもわかる |

他にもいろいろな情報が取得できます。

* https://developer.foursquare.com/docs/responses/venue

# ベニュー詳細

# カテゴリ一覧取得


# リソース

## イケてるライブラリたち

* https://developer.foursquare.com/resources/libraries

## フォーラム

* http://stackoverflow.com/questions/tagged/foursquare

## 公式開発ブログ

* http://engineering.foursquare.com/

## 参考リンク

* [foursquareのOAuth認証部分をライブラリに切り出してみた](http://blog.koogawa.com/entry/2013/11/04/212403)
* [foursquareが提供するネットワークライブラリFSNetworkingを使ってみた](http://blog.koogawa.com/entry/2013/11/04/043230)
* [foursquare - koogawa blog](http://blog.koogawa.com/archive/category/foursquare)