=======
概要
=======

http://developer.foursquare.com/docs/overview.html

.. The foursquare API uses many of the same standards as other APIs
   you may be familiar with. All requests are simple GET or POST
   requests that return JSON or JSONP respones. (Note that the request
   parameters are not JSON, they are standard HTTP keys and values.)
   All authentication is via OAuth2, which means that all requests
   MUST be https.

The foursquare API はあなたが慣れ親しんでいるであろう他のAPIと同様に、
多くのWeb標準を使用しています。全てのリクエストはJSONかJSONPを返す単純
なGETかPOSTリクエストです。 (リクエストのパラメータはJSONではなく、標準
的なHTTPのキーバリューであることに注意してください) 全ての認証はOAuth2
で行われ、それはすなわち、全てのリクエストはhttpsでなければ *ならない*
ということです。

-------------------
APIの利用回数制限
-------------------


.. Usage of the API is subject to rate limits. The limits are based on
   a moving window that tracks the number of requests you send per
   hour.

APIの利用回数は制限されます。この制限は一時間毎に送られるリクエストの数
を追跡し、随時変更されます。

.. The default limit is 200 requests per hour per method. The rate
   limiting is applied to the OAuth user or, if none is present, the
   IP address.

最初の制限はメソッド毎に一時間に200リクエストです。この制限はOAuthユー
ザか、そうでなければIPアドレス毎にかかります。

.. Your application should try to play nicely against our methods. For
   instance, cache results on your side wherever possible (e.g.,
   /venue calls usually tend to be more long-lived than others).

あなたのアプリケーションはfoursquareのメソッドを優しく扱わなければなり
ません。具体的には、アプリケーション側で可能なかぎりキャッシュすること
です。 (例: /venue は他のメソッドに比べて通常長い期間有効です)

.. We're still learning about your apps and tweaking these caps. If
   your application runs into any of our bounds and you think you
   could use more, write us at api@foursquare.com with your client id
   and IP addresses.

私たちはあなたのアプリケーションについて調査しています。もし、あなたの
アプリケーションが私たちの制限にあたり、あなたがもっと使いたいと思う場
合には、 api@foursquare.com にあなたのクライアント IDとIPアドレスととと
もに連絡してください。

---------------
レスポンス
---------------

全てのレスポンスは以下のような形式で返されます。::
    
    {
      "meta": {
        "code": 200,
         ...errorType and errorDetail...
      },
      "notifications": {
         ...notifications...
      },
      "response": {
         ...results...
      }
    }

.. The errorType is detailed information intended for the application
   developer. We ask applications to show an appropriate error to
   their users by handling the error codes listed below. We will add
   additional types as needed. The deprecated type may be returned
   even if a request is successful.

`errorType` はアプリケーション開発者にとって詳細な情報を提供します。私
たちは後述するエラーコードに応じて適切に扱ってくれるようにアプリケーショ
ンに対して適切なエラーを返します。私たちは、必要であればエラータイプを
追加します。 `deprecated` 型はリクエストが成功しても返されることがあります。

.. The meta section may also contain a message which provides
   additional information intended to help developers debug problems.

`meta` セクションは開発者が問題を解決する手助けをするような追加の情報を
`message` に含んでいる場合があります。

.. Certan requests may also contain notifications as a top-level item
   based on a just-submitted checkin or other user actions.

適切なリクエストは **notification** をトップレベルアイテムに含んでいる
場合があります。これは、今まさにcheckinや他の行動を起こしたという情報です。

.. To use JSONP, add a callback=XXX parameter to your request and we
   will respond with XXX(response). In the case of JSONP, we always
   return 200 (except in the case of 500's) so the brower will allow
   the response to be handled by your code, but the true HTTP response
   code can be obtained from the code in the meta response.

JSONPを使うには、 `callback=XXX` というパラメータをリクエストに含めてく
ださい。そうすれば、 XXX(response) が返されます。JSONPの場合、私たちは
常に(500番台以外)、200を返します。そのため、ブラウザはレスポンスをあな
たのコードで扱えます。しかし、本当のHTTPレスポンスコードは、レスポンス
の `meta` 内の `code` に含まれています。

------
エラー
------

.. As much as possible, foursquare attempts to use appropriate HTTP
   status codes to indicate the general class of problem, and this
   status code is repeated in the code section of the meta response.

問題を指し示すために、foursquareは可能なかぎり適切なHTTPステータスコー
ドを使用します。そして、そのステータスコードは `meta` レスポンスの
`code` セクションにて繰り返されます。

.. list-table:: 
   :widths: 30 70

   * - 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` に詳細が付け加えられます。これらは必ず以下の中の一つです。

.. list-table:: 
   :widths: 30 70

   * - invalid_auth
     - OAuthトークンがないか、不正です
   * - param_error
     - 要求されたパラメータは存在しないかパラメータが不正です。これはパスの中のリソースIDが間違っている場合にも起こります
   * - endpoint_error	
     - リクエストしたパスは存在しません
   * - not_authorized	
     - 認証は成功しましたが、プライバシー制限により使用しているユーザはこの情報を見られません
   * - rate_limit_exceeded	
     - この時間での利用回数制限を超えました
   * - deprecated
     - このリクエストに関するなんらかの機能は廃止された、あるいはレスポンスの形式が変更されました
   * - server_error	
     - 現在サーバに問題が起きています。最新情報は http://status.foursquare.com を見てください。
   * - other	
     - なんらかの他の種類のエラーが発生しました