Foursquare API ドキュメンテーション日本語化プロジェクト¶

このサイトは https://developer.foursquare.com/overview/ で公開されている Foursquare API の日本語訳を作成・公開および配布するプロジェクトです。Foursquare 非公式のプロジェクトのため、問題があればこのサイトを削除いたします。

The Foursquare API¶

Foursquare は開発者に多くの製品を提供していますが、私たちの API では Foursquare と Swarm のユーザがモバイルアプリケーションやウェブサイトでできるすべてのことを行うことができます。次を始める前に必ずスタートガイドをお読みください。

API エンドポイント¶

API とそのエンドポイント全体の概要です。 Tips、チェックイン、友達、そしてベニューの情報を検索するために API ドキュメントをお読みください。

リアルタイム API¶

ベニュープッシュ API はユーザがベニューでさまざまな行動を起こした際にベニューの管理者に通知し、ユーザプッシュ API はユーザが任意の場所にチェックインした際に開発者に通知します。

ベニューサービス¶

場所のデータベースが必要ですか？ベニューサービスは開発者が場所を検索したり、住所・評判・Tips・写真のような豊富な情報にアクセスすることを許可します。アプリケーションに適切な帰属が与えられている限り、ユーザの認証を必要とせず自由に利用することができます。

Merchant Platform¶

The Merchant Platform allows developers to write applications that help registered venue owners manage their Foursquare presence and specials.

詳細なガイド¶

接続¶

登録¶

アプリケーションを登録し、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)

レスポンス & エラー¶

レスポンス¶

すべてのレスポンスは概ね次のようになります:

{
  "meta": {
    "code": 200,
     ...errorType and errorDetail...
  },
  "notifications": {
     ...notifications...
  },
  "response": {
     ...results...
  }
}

errorType はアプリケーション開発者向けの詳細な情報です。以下に示すエラーコードを処理することで、適切なエラーメッセージをユーザに表示左折ことができます。必要に応じて追加の type を追加する場合があります。リクエストが成功した場合でも、非推奨な type が返ってくる場合があります。

meta セクションには、開発者がデバッグする際に役立つ追加情報を提供するメッセージも含まれます。

特定のリクエストには、チェックインやほかのユーザアクションに基づくトップレベルの項目としての通知も含まれます。

JSONP を用いて、リクエストに callback=XXX を追記すると XXX（レスポンス）というレスポンスが返ってきます。 JSONP の場合、つねにステータスコード 200 を返すため（例外的に 500 番台の場合もあります）、ブラウザはコードでレスポンスの処理を行えますが、実際の HTTP ステータスコードは meta レスポンスの code から取得できます。

応答の内容は、API リクエストで渡す m パラメータによって異なる場合があります。詳細な情報は、バージョンと国際化のドキュメントを参照ください。

エラー¶

Foursquare は可能な限り問題の一般的なクラスを示すのに適切な HTTP ステータスコードを使用します。このステータスコードは meta レスポンスの code セクションで繰り返されます。

400 (Bad Request)	パラメータが無効か、必須パラメータが欠けています。OAuth トークンが指定されていない場合やリソース ID が正しく指定されていない場合も該当します。
401 (Unauthorized)	OAuth トークンが無効です。
403 (Forbidden)	リクエストしようとした情報を参照できません。例えば、友達でないユーザに関するすべての情報を参照しようとした場合に発生します。
404 (Not Found)	エンドポイントが存在しません。
405 (Method Not Allowed)	GET のみのエンドポイントで POST しているか、またはその逆の操作を行なっています。
409 (Conflict)	リクエストを完了できませんでした。レスポンスに含まれる情報を使用してリクエストを変更し、再びリクエストを行います。
500 (Internal Server Error)	Foursquare のサーバが不調です。おそらくリクエストは有効ですが、あとで再試行する必要があります。

さらなる詳細は errorType に記述されています。以下のいずれかになります。

`errorType`	ステータスコード	説明
invalid_auth	401	OAuth トークンが提供されていないか無効です。
param_error	400	必要なパラメータが欠けているか不正です。パス内のリソース ID が正しくない場合にも使用されます。
endpoint_error	404	リクエストしようとしたパスが存在しません。
not_authorized	403	認証は成功していますが、プライバシー制限のため情報を見ることを許可されていません。
rate_limit_exceeded	403	時間あたりのレート制限を超えています。
quota_exceeded	429	一日あたりのコールクォータを超えています。
deprecated	200	リクエストに関する何らかの廃止された機能を使用しているか、レスポンスフォーマットが変更されている場合があります。
server_error	場合による	サーバ側で問題が発生しています。status.foursquare.com で状態を確認してみてください。
other	場合による	ほかのエラーが発生しています。

エラーには errorDetail フィールドが含まれ、開発者向けの追加情報が記述されています。場合によってサーバの errorMessage を含む場合があります。これはクライアントがユーザに直接表示するためのローカライズされた文字列です。

参考

Responses & Error (https://developer.foursquare.com/overview/responses)

バージョンと国際化¶

バージョン¶

すべての API リクエストには Foursquare が返すレスポンスの種類を操作するための 2 つの特別なパラメータが必要です。必要な形式は次のとおりです:

v パラメータ: Foursquare から要求する API のバージョンを表す日付です。
m パラメータ: Swarm または Foursquare ライクのレスポンスのどちらを使用するかを指定します。

POST リクエストを含むすべての API リクエストにこれらのパラメータを含める必要があります。したがって、これらのパラメータを含めた完全な API リクエストは次のようになります:

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

`v` パラメータ¶

v パラメータは開発者が Foursquare API の変更を各自の計画で自由に適用できるように設計されています。 v パラメータの値は YYYYMMDD の日付フォーマットとなっており、「この日付までの API の変更に対応しています」ということを意味しています。具体的な例として、将来の変更を導入してすべての id フィールドが foo となった場合を考えてみます。 API リクエストが v=YYYYMMDD またはそれより前の値を渡している場合、 id フィールドが呼ばれたままになります。しかし、パラメータの値をより新しい日付に更新した場合は foo フィールドが採用されます。

すべての API コールで 1 つの日付を設定し、この日付で API 呼び出しによるアプリケーションの起動をお勧めします。 1) 数ヶ月に一度日付を更新する 2) Foursquare が古いバージョンから変更を加えたかチェックする 3) これらの変更に対応するように実装を変更することを提案します。

どのような場合でもつねに現在の日付を渡すべきではありません。 一つの日付を選択し、起こりうる変更に対応する準備が整うまで値を更新しないでください。また、リクエストごとに渡されるバージョンパラメータは API の URL パスの一部としての v2 とは無関係に v2 であるべきです。

非推奨¶

Foursquare の成長と発展にともなって、API やそのバージョンの特定の部分を非推奨とする場合があります。非推奨のバージョンやエンドポイントを使用した際のリクエストに対するレスポンスは、 meta セクションにそれらに関する情報が含まれます – errorType の deprecated を確認してください。時間とともに従来の動作や API のバージョンのサポートを段階的に廃止しますが、移行には少なくとも数ヶ月はかかる見込みです。

開発者に対して差し迫る変更について警告するため、変更の影響を受ける開発者に E メールを送信し、変更が実際に反映される前に「API brownouts」を行い変更の影響をシミュレートします。そのため、開発者アカウントに紐づけられた E メールアドレスを頻繁にチェックしてください。

`m` パラメータ¶

Swarm と Foursquare のどちらでも動作する API は 1 つだけであるため、場合によっては同じエンドポイントについて、レスポンスに対して異なる情報を返すことが理にかなっていることがあります。 m (mode) パラメータは Swarm または Foursquare スタイルの API レスポンスを使用するかどうかを指定できます – 例えば、Users Detail エンドポイントは m=swarm でチェックインの情報を返しますが、 m=foursquare でユーザの Tips について返す場合があります。

アプリケーションが大幅に変更されない限り、 m パラメータの値を変更して渡す必要はありません。

国際化¶

リクエストの Accept-Language HTTP ヘッダにてロケールを指定できます。 locale=XXX パラメータも追加できますが、HTTP ヘッダの指定が優先されます。現在は en（デフォルト）、fr、de、it、ja、th、tr、ko、ru、pt、id をサポートしています。

ロケールを指定しない場合、地理的なエンティティ（例: 都市名）についてはそのベニューのある国でもっとも使われる言語が選択されます。

Foursquare はベニューカテゴリに対して多くの国ごとのサブカテゴリをサポートしています。特定の国でのみ適用されるべきカテゴリについては、」Suggested Countries」がカテゴリツリーにリストアップされます。

参考

Versioning & Internationalization (https://developer.foursquare.com/overview/versioning)

帰属とリンク¶

帰属なしに引用できないのと同様に、Foursquare のデータを利用する際にはクレジットが必要です。特定の状況下では、その他の条件が適用される場合があります。

Foursquare のベニューを使用する際の帰属¶

API を用いるもっとも一般的な方法はベニューのデータベースを使用することであり、特定の帰属ポリシーが適用されます。ベニューデータを使用しない場合（クイックチェック: venues/* エンドポイントを使用しますか？）、ビジュアルアトリビューションまでスキップできます。

リンク: 基本的なデータ¶

基本的なデータの先¶

検索結果¶

ビジュアルアトリビューション¶

参考

Attribution & Linking (https://developer.foursquare.com/overview/attribution)

参考

About (https://developer.foursquare.com/overview/)

API エンドポイント¶

リソース¶

サポート¶

アナウンス¶

Foursquare API に関する重要なアナウンスは、アプリケーションを作成した Foursquare ユーザが設定した E メールアドレスに送信されます。開発者には、企業や法人の代わりに個人のアカウントを使用せず、複数の受信ボックスにヒットする E メールアドレスをもつ Foursquare アカウントを作成することをお勧めします。

Twitter でも最新情報をチェックできます: @foursquareAPI

開発者フォーラム¶

Foursquare API について Stack Overflow で質問するとよいでしょう。特にプログラミング言語特有の問題について投稿されています:

https://stackoverflow.com/questions/tagged/foursquare

Stack Overflow コミュニティに加えて、Foursquare のメンバーは積極的にサイトを確認し、頻繁に質問に答えています。

参考

Support (https://developer.foursquare.com/overview/support)

Foursquare API ドキュメンテーション日本語化プロジェクト¶

The Foursquare API¶

API エンドポイント¶

リアルタイム API¶

ベニューサービス¶

Merchant Platform¶

詳細なガイド¶

接続¶

登録¶

アクセストークン¶

iOS / Android¶

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

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

リクエスト¶

認証¶

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

表示形式¶

OAuth に関する注意¶

レスポンス & エラー¶

レスポンス¶

エラー¶

バージョンと国際化¶

バージョン¶

v パラメータ¶

非推奨¶

m パラメータ¶

国際化¶

帰属とリンク¶

Foursquare のベニューを使用する際の帰属¶

リンク: 基本的なデータ¶

基本的なデータの先¶

検索結果¶

ビジュアル アトリビューション¶

API エンドポイント¶

リソース¶

サポート¶

アナウンス¶

開発者フォーラム¶

`v` パラメータ¶

`m` パラメータ¶

ビジュアルアトリビューション¶