http://developer.foursquare.com/docs/venues/venues.html
https://api.foursquare.com/v2/venues/VENUE_ID
venueの詳細情報を得ます。これには位置情報、mayorship、tag、tips、specials、カテゴリーを含みます。
認証済みユーザであれば、今そこに誰がいるかの情報も得ることが出来ます。
もし、与えられたvenue IDが他の “master” venueと合併したものであった場合、レスポンスにはエラーの代わりに “master”の情報が記載されます。
| HTTP メソッド | GET |
|---|---|
| 認証が必要か | NO |
http://developer.foursquare.com/docs/venues/add.html
https://api.foursquare.com/v2/venues/add
ユーザにvenueを追加させます。
もしこのメソッドがエラーを返した場合、ユーザは再度編集しても構いません。さらに、venueの名前だけを指定した”venueなし(venuless)”のcheck-inを行う、”気にしないでとにかくcheck-inする(never mind, check-in here anyway)”と表示しても構いません。また、めったにないことですが、ユーザが重複したvenueを作ることもあります。
全てのフィールドはオプションですが、正しい住所か緯度・経度のペアのどちらかは必須です。私たちは開発者にどの場合でも緯度経度を提供するように勧めます。
また、オプションでそのvenueに設定したいカテゴリー(primarycategoryid)を渡すことも出来ます。/categoriesメソッドを使うことで、カテゴリーの完全なリストを得ることが出来ます。Venueを追加するときは、アプリケーションがカテゴリーの階層構造を表示し、ユーザが適切なカテゴリーを選択できるようにしてください。
| HTTP メソッド | POST |
|---|---|
| 認証が必要か | YES |
特別に記載されていない限り、全てのパラメータはオプショナルです。
| name | Habana Outpost | 必須venueの名前 |
|---|---|---|
| address | 1313 Mockingbird Lane | 住所 |
| crossStreet | at Fulton St | 一つ以上のもっとも近い通り名 |
| city | New York | 都市名 |
| state | new York | 州、省、県 |
| zip | AE1234 | zipあるいは郵便番号 |
| phone | 00 01 23 1234 | 電話番号 |
| ll | 44.3,37.2 | 出来る限り正確な緯度経度 |
| primaryCategoryId | 4bf58dd8d48988d1d4941735 | 設定したいカテゴリーのID |
http://developer.foursquare.com/docs/venues/categories.html
https://api.foursquare.com/v2/venues/categories
venueに付けられる、カテゴリーの階層構造のリストを返します。トップレベルのカテゴリーはvenueに割り当てられないためにIDを持たないことに注意してください。
クライアントアプリケーションを設計するときに、セッションごとに一回だけこのカテゴリーのリストをダウンロードするようにしてください。また、古い情報を扱うことを避けるために、1週間以上キャッシュしないようにしてください。
カテゴリーの画像は三種類のサイズがAPIから取得できます。
標準では、APIメソッドはこのフォーマットで32pxの画像を返します。
http://foursquare.com/img/categories/food/coffeeshop.png
異なるサイズの画像が欲しい場合は、単に違う語を後ろに付けてください。
| HTTP メソッド | GET |
|---|---|
| 認証が必要か | NO |
なし
http://developer.foursquare.com/docs/venues/search.html
https://api.foursquare.com/v2/venues/search
現在の場所に近いvenueのリストを返します。また、検索語が与えてマッチするものだけを返すことも出来ます。
もし緯度経度が与えられた場合、それぞれのvenueは距離を含みます。もし認証済みであれば、このメソッドはユーザとユーザのfriendに関連するvenueのメタデータを返します。もし認証されていない場合は、これらの情報は得られません。
レスポンスのvenueの中に含まれているフィールドのほとんどはオプションであることに注意してください。ユーザは住所、都市名がないvenueを作ることもあります(venueは代わりに緯度経度で作られています)。あなたのクライアントはこのような状態を安全に扱える必要があります。
また、 stats 部分でvenueに関するいくつかの数値情報が含まれることに注意してください。herenowは現在そこにいる人の数です(この値は0の場合があります)。
| HTTP メソッド | GET |
|---|---|
| 認証が必要か | NO |
特別に記載されていない限り、全てのパラメータはオプショナルです。
| ll | 44.3,37.2 | ユーザの場所の緯度経度。レスポンスには距離も含まれる場合があります |
|---|---|---|
| llAcc | 10000.0 | ユーザの緯度経度情報の精度をメートルで示したもの |
| alt | 0 | ユーザの高度をメートルで示したもの |
| altAcc | 10000.0 | ユーザの高度情報の精度をメートルで示したもの |
| query | donuts | タイトルを検索する検索語 |
| limit | 100 | オプションレスポンスの数。最大500 |
| intent | checkin | オプションこの検索を行う目的を示します。もし、ユーザが近くのvenueにcheck inを行いたいのであれば、checkin(デフォルト)としてください。結果は私たちがユーザがcheckinをしたいと思われる順番にソートされます。もし、与えれたvenue名と場所に合うようなvenueを見つけたいのであれば(例: 3rdパーティのvenueとfoursquareのvenueとをマッチングさせるためなど)、matchを与えてください。結果はベストマッチが最初に、続いて距離やスペルミスやバリエーションがあるものが続きます |
| venues | venueのグループが複数含まれているオブジェクトの配列です。それぞれのgroupはfavorites、trending、 あるいはnearby(人間が読める形式の近くの名前、”Nearyby favorites”など) といったtypeを持ちます。また、Venueレスポンスの配列のitemを持ちます。私たちはクライアントに対して、グループのタイプが増えたり減ったり、trendingに不明瞭なオブジェクトのグループが表示されたり、新しい結果を捨てるガラクタ入れの中のよく分からないグループがあったりても問題ないようにして欲しいと考えています。例えば、選挙の日にはfoursquareは一時的に投票所グループを作るかもしれませんが、あなたのアプリケーションはそれをちゃんと丁寧に扱えなくてはなりません。 |
|---|
http://developer.foursquare.com/docs/venues/herenow.html
https://api.foursquare.com/v2/venues/VENUE_ID/herenow
今現在、与えられたvenueに何人の人がいるかを返します。さらに、そのユーザの最初のページ、frinedのfirstページ、現在のユーザが認証されているかを返します。(訳註: 自信なし)
これは実験的なAPIです。私たちは技術的革新によってユーザの全てのcheckinを効率的に返せるようになったことに興奮していますが、まだ、これが正しい方法なのかどうかを検証中です。メーリングリストで意見とフィードバックをお待ちしています。
| HTTP メソッド | GET |
|---|---|
| 認証が必要か | NO |
http://developer.foursquare.com/docs/venues/tips.html
https://api.foursquare.com/v2/venues/VENUE_ID/tips
venueのtipsを返します。
| HTTP メソッド | GET |
|---|---|
| 認証が必要か | NO |
特別に記載されていない限り、全てのパラメータはオプショナルです。
| VENUE_ID | XXX123YYYY | 必須tipsを付け加えたいvenueの場所 (訳註: こぴぺしてしまった？) |
|---|---|---|
| sort | recent | recentあるいはpopularのどちらか |
http://developer.foursquare.com/docs/venues/marktodo.html
https://api.foursquare.com/v2/venues/VENUE_ID/marktodo
venueをtodoとして印をつけることが出来ます。オプションとして、文字列を追加することも出来ます。
| HTTP メソッド | POST |
|---|---|
| 認証が必要か | YES |
特別に記載されていない限り、全てのパラメータはオプショナルです。
| VENUE_ID | XXX123YYYY | 必須TODOとして印をつけたいvenueのID |
|---|---|---|
| text | The donuts are tasty! | このtipsの文字列 |
http://developer.foursquare.com/docs/venues/flag.html
https://api.foursquare.com/v2/venues/VENUE_ID/flag
ユーザがvenueのなにかが間違っているという印をつけます。
フラグはモデレートの列に入れられます。もし、closedフラグが承認された場合、そのvenueは検索結果に現れることはなくなります。mislocatedかvenueのduplicateの場合、モデレータは修正を試みます。もし、ユーザが住所が違う(mislocated)venueの正しい住所を持っている場合、変更を提案するを代わりに使ってください。
| HTTP メソッド | POST |
|---|---|
| 認証が必要か | YES |
特別に記載されていない限り、全てのパラメータはオプショナルです。
| VENUE_ID | AVNU234 | 必須変更が提案されているvenueのID |
|---|---|---|
| problem | mislocated | 必須mislocatedclosedduplicatのどれか |
なし
http://developer.foursquare.com/docs/venues/proposeedit.html
https://api.foursquare.com/v2/venues/VENUE_ID/proposeedit
venueの情報を変える提案をします。
もしユーザが正しい住所を知っていれば、このメソッドを使って保存してください。そうでなければ、代わりにフラグを付けるを使ってフラグをたててください(この場合、新しい住所あるいは緯度経度を指定する必要はありません)。
| HTTP メソッド | POST |
|---|---|
| 認証が必要か | YES |
特別に記載されていない限り、全てのパラメータはオプショナルです。
| VENUE_ID | AVNU234 | 必須変更を提案したいvenueの識別子 |
|---|---|---|
| name | Habana Outpost | venueの名前 |
| address | 1313 Mockingbird Lane | 住所 |
| crossStreet | at Fulton St | 一つ以上のもっとも近い通り名 |
| city | New York | 都市名 |
| state | new York | 州、省、県 |
| zip | AE1234 | zipあるいは郵便番号 |
| phone | 00 01 23 1234 | 電話番号 |
| ll | 44.3,37.2 | 出来る限り正確な緯度経度 |
| primaryCategoryId | 4bf58dd8d48988d1d4941735 | 設定したいカテゴリーのID |
なし
