バージョンと国際化¶

バージョン¶

すべての 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)

バージョンと国際化¶