接続¶

登録¶

アプリケーションを登録し、Foursquare API クレデンシャルを取得してください。

アクセストークン¶

アクセストークンを使用することで、アプリケーションはユーザの代わりに Foursquare にリクエストを送信できるようになります。各アクセストークンはユーザと Consumer key で一意の値となっています。アクセストークンは無期限ですが、ユーザが無効にする場合があります。アプリケーションが Foursquare ユーザの情報にアクセスする必要がない場合、ユーザレスサーバインテグレーションまで手順をスキップできます。

現時点では、Foursquare は Foursquare と Swarm に代わってアプリケーションを認証するための、単一認証機構のみをサポートしています。

iOS / Android¶

ネイティブな認証は、ユーザが Foursquare に接続するのにもっとも簡単な方法です。次に示す Web ベースの OAuth のフローとは異なり、ネイティブなフローはユーザのスマートフォンにすでにインストールされている Foursquare アプリを利用するため、あなたのアプリ内で Foursquare に再ログインする手間を省略できます。この方法は、唯一 Facebook を経由して Foursquare にログインできるフローです。

ネイティブな認証を使用するには、あなたの iOS または Android アプリにユーティリティクラスを組み込みます。詳細な使用方法については各リポジトリの README を参照ください。

Web アプリケーションのコードフロー¶

推奨される OAuth 2.0 のフローは次のとおりです:

ユーザに次の URL を与えます:

https://foursquare.com/oauth2/authenticate
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

ユーザが承諾したら、以下へリダイレクトします:
```
https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
```

アプリケーションサーバにてステップ 2 で取得した CODE をアクセストークンと交換します。次のリクエストを送信してください:

https://foursquare.com/oauth2/access_token
    ?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &grant_type=authorization_code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &code=CODE

レスポンスは JSON 形式となります:
```
{ access_token: ACCESS_TOKEN }
```

ユーザのアクセストークンをデータベースに保存してください

Web アプリケーションのトークンフロー¶

サーバで動作するコードが実質的にない場合、以下に示すトークンフローを使用できます。

認証させるユーザを以下へリダイレクトさせます:

https://foursquare.com/oauth2/authenticate
    ?client_id=CLIENT_ID
    &response_type=token
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI

ユーザが承認したら、以下へリダイレクトします:
```
https://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN
```

アプリケーションに複数のリダイレクト URI を登録する場合、redirect_uri パラメータの値を変更することで使用する URI を指定できます。 Web connect を有効にすれば、ユーザは最初のリダイレクト URI へリダイレクトされます。

リクエスト¶

一度アクセストークンを入手すれば、API エンドポイントの使用は簡単です。 GET または POST リクエストに oauth_token=ACCESS_TOKEN を追記してください。例えば、コマンドラインでは次のようになります:

curl https://api.foursquare.com/v2/users/self/checkins?oauth_token=ACCESS_TOKEN&v=YYYYMMDD

認証¶

上の例では /authorize の代わりに /authenticate を使用していますが、これは OAuth プロトコルで指定されているためです。 /authenticate はユーザ認証とアプリケーションの認証の両方を処理し、ユーザがすでにアプリケーションを認証していれば自動的にリダイレクトされることに注意してください。 一方、 /authorize はつねに認証リクエストを承諾するようユーザに指示します。

ユーザの初回認証時に Web アプリケーション側でセッション Cookie を使用し、ユーザの身元を確認することをお勧めします。 Foursquare 内部のすべての Webview は同じ Cookie を共有しているため、以後すべての通信はセッション Cookie によってユーザの認証を行い、ユーザがアプリケーションを操作するたびにサーバのリダイレクトを回避できます。

ユーザレスサーバインテグレーション¶

ベニュー検索など特定のユーザの情報に関係しないエンドポイントのいくつかは、ユーザレスアクセスが可能です（ユーザがアクセスのためにアプリケーション内で認証する必要がないということです）。ユーザレスリクエストを生成するには、リクエスト URL の認証トークンの代わりに consumer key のクライアント ID とシークレットを指定します:

https://api.foursquare.com/v2/venues/search?ll=40.7,-74&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&v=YYYYMMDD

エンドポイントごとにどのレベルの権限が必要か確認するには、 API エンドポイントページの上部のフィルターで確認してください。

表示形式¶

通常、Foursquare は認証ダイアログに表示する適切なサイトの形式を自動で検出します。認可（authorize）または認証（authenticate）URL に display=XXX を追記することで表示形式を指定することも可能です。サポートされる表示形式は touch および webpopup となります。 webpopup ディスプレイを使用する場合を除き、表示形式を指定することをお勧めしません。 webpopup モードでは、ポップアップウィンドウにて認証ダイアログを表示させ、呼び出し元のウィンドウのコールバックにリダイレクトし、アプリケーションの認可後にポップアップウィンドウが閉じられます。

OAuth に関する注意¶

API リクエストは api.foursquare.com に対して行いますが、OAuth トークンと認証リクエストは foursquare.com に対して行うことに注意してください。

Android 上で実行するうえでの問題は、Foursquare がワイルドカード SSL 証明書を用いることです。詳細は、こちらの Stack Overflow の回答を参照ください。

現時点では OAuth アクセストークンは期限切れではありませんが、期限切れの可能性を考慮してください。また、ユーザは Foursquare の設定画面からいつでも切断することができます。 /authorize を使用するとユーザを再認証してアプリケーションを再認可する手続きを踏むため、別のアカウントでログインするオプションをユーザに与えることができます。

参考

Connecting (https://developer.foursquare.com/overview/auth)