http://developer.foursquare.com/docs/overview.html
The foursquare API はあなたが慣れ親しんでいるであろう他のAPIと同様に、多くのWeb標準を使用しています。全てのリクエストはJSONかJSONPを返す単純なGETかPOSTリクエストです。 (リクエストのパラメータはJSONではなく、標準的なHTTPのキーバリューであることに注意してください) 全ての認証はOAuth2で行われ、それはすなわち、全てのリクエストはhttpsでなければならないということです。
APIの利用回数は制限されます。この制限は一時間毎に送られるリクエストの数を追跡し、随時変更されます。
最初の制限はメソッド毎に一時間に200リクエストです。この制限はOAuthユーザか、そうでなければIPアドレス毎にかかります。
あなたのアプリケーションはfoursquareのメソッドを優しく扱わなければなりません。具体的には、アプリケーション側で可能なかぎりキャッシュすることです。 (例: /venue は他のメソッドに比べて通常長い期間有効です)
私たちはあなたのアプリケーションについて調査しています。もし、あなたのアプリケーションが私たちの制限にあたり、あなたがもっと使いたいと思う場合には、api@foursquare.comにあなたのクライアント IDとIPアドレスととともに連絡してください。
全てのレスポンスは以下のような形式で返されます。:
{
"meta": {
"code": 200,
...errorType and errorDetail...
},
"notifications": {
...notifications...
},
"response": {
...results...
}
}
errorTypeはアプリケーション開発者にとって詳細な情報を提供します。私たちは後述するエラーコードに応じて適切に扱ってくれるようにアプリケーションに対して適切なエラーを返します。私たちは、必要であればエラータイプを追加します。deprecated型はリクエストが成功しても返されることがあります。
metaセクションは開発者が問題を解決する手助けをするような追加の情報をmessageに含んでいる場合があります。
適切なリクエストはnotificationをトップレベルアイテムに含んでいる場合があります。これは、今まさにcheckinや他の行動を起こしたという情報です。
JSONPを使うには、callback=XXXというパラメータをリクエストに含めてください。そうすれば、 XXX(response) が返されます。JSONPの場合、私たちは常に(500番台以外)、200を返します。そのため、ブラウザはレスポンスをあなたのコードで扱えます。しかし、本当のHTTPレスポンスコードは、レスポンスのmeta内のcodeに含まれています。
問題を指し示すために、foursquareは可能なかぎり適切なHTTPステータスコードを使用します。そして、そのステータスコードはmetaレスポンスのcodeセクションにて繰り返されます。
| 400 (Bad Request) | パラメータが不正な場合、あるいはパラメータがない場合。OAuthトークンがない場合とresource IDがpathに正しく指定されていない場合を含みます。 |
| 401 (Unauthorized) | OAuthトークがありますが不正です |
| 403 (Forbidden) | 要求された情報は現在のユーザは見られません。例えば、情報を読みたいユーザとfriendではないなどです |
| 404 (Not Found) | エンドポイントがありません |
| 405 (Method Not Allowed) | GETしか受け付けないエンドポイントにPOSTを使用したなどが考えられます |
| 500 (Internal Server Error) | fousquareのサーバは不幸です。リクエストはおそらく正しいのですが後ほどもう一度試してください |
errorTypeに詳細が付け加えられます。これらは必ず以下の中の一つです。
| invalid_auth | OAuthトークンがないか、不正です |
| param_error | 要求されたパラメータは存在しないかパラメータが不正です。これはパスの中のリソースIDが間違っている場合にも起こります |
| endpoint_error | リクエストしたパスは存在しません |
| not_authorized | 認証は成功しましたが、プライバシー制限により使用しているユーザはこの情報を見られません |
| rate_limit_exceeded | この時間での利用回数制限を超えました |
| deprecated | このリクエストに関するなんらかの機能は廃止された、あるいはレスポンスの形式が変更されました |
| server_error | 現在サーバに問題が起きています。最新情報はhttp://status.foursquare.comを見てください。 |
| other | なんらかの他の種類のエラーが発生しました |