Help us understand the problem. What is going on with this article?

foursquare APIでできること

More than 3 years have passed since last update.

まずは、foursquare デベロッパーサイトよりアプリケーション登録をしましょう。

ここで発行される CLIENT IDCLIENT SECRET を使ってfoursquare APIにアクセスできます。

概要

APIリクエスト

認証の有無によってリクエストパラメータが変わってきます。また、認証ありの場合、そのユーザに最適化された結果が返ってくるようになります。

認証あり

※最初に CLIENT IDCLIENT SECRET で認証を行い、 oauth_token を発行しておきます。→認証手順

https://api.foursquare.com/v2/hoge/fuga
?param1=value1
&param2=value2
&oauth_token=YOUR_OAUTH_TOKEN
&v=YYYYMMDD

認証なし

https://api.foursquare.com/v2/hoge/fuga
?param1=value1
&param2=value2
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&v=YYYYMMDD

バージョニング

すべてのリクエストには v=YYYYMMDD が必要です。foursquare APIは YYYYMMDD に指定した日付時点の仕様で動作します。例えば、v=20140208 を指定しておけば、2014年2月9日にfoursquare側で大幅な仕様変更があった場合も、2014年2月8日時点での仕様で動作し続けるため、突然アプリケーションが動かなくなった!ということを防げます。

国際化

例えば、foursquareのカテゴリ一覧を取得する場合、日本語環境では 水族館 、英語環境では Aquariums といった具合に、ユーザの環境に適した表記が使用されます。これは、APIリクエスト時の HTTP ヘッダ Accept-Language によって変わってきます。通常はこれで問題無いと思いますが、locale=XX パラメータを使って強制的に言語を指定することも可能です。現在は、en, es, fr, de, it, ja, th, tr, ko, ru, pt, id がサポートされています。

回数制限

認証の有無、APIの種類によって変わってきます。

認証なしで使う場合

  • venues/ から始まるAPI(venues/search, venues/explore等)は、ひとつのアプリケーションにつき、 1時間あたり合計5,000回まで
  • それ以外のAPIはひとつのアプリケーションにつき、 1時間あたり合計500回まで
  • 上の2種類は別々にカウントされるので、例えば venues/search を5,000回使ってしまった場合でも、tips/ APIを使うことはできる

認証ありで使う場合

  • ひとつのOAuth Tokenにつき、 1時間あたり合計500回まで

残り回数

残りの使用可能回数は、APIレスポンスの X-RateLimit-RemainingX-RateLimit-Limit で確認できます。

これで足りない場合は、foursquare に連絡することでリミットを上げてくれるようです。

エンドポイント

ベニュー検索

https://api.foursquare.com/v2/venues/search

緯度経度 または 地域名 からベニューリストを検索します。認証不要ですが、認証ありの場合はそのユーザ向けにパーソナライズされた結果が返ってきます。

  • HTTPメソッド:GET
  • 認証:不要

パラメータ

キー 必須 解説
ll 44.3,37.2 緯度経度をカンマ区切りで指定。
query apple 検索ワードを指定。
limit 10 結果件数を指定。最大50まで。
intent checkin 検索の意図を指定。ベニューの表示順や検索範囲に影響が出てくる。checkin (デフォルト)を指定すると、ユーザにチェックインされやすいベニュー順に結果が返ってくる。global を指定すると世界中のベニューが検索範囲になる。
radius 800 検索半径をメートルで指定。
categoryId asad13242l,btbe24353m 結果をカテゴリで絞り込みたい場合に使用。カテゴリ名ではなく、カテゴリIDを指定。

他にもいろいろ指定できます。

レスポンス

Compact Object 形式(簡易表示)で返ってきます。Compact Objectの場合、ベニュー名や住所などの情報は含まれますが、Tipsや写真などの詳細情報は含まれません。

フィールド 解説
id ユニークなベニューID(例えば秋葉原駅は 4b19f917f964a520abe623e3)
name ベニュー名
contact Twitterアカウントや電話番号
location 住所や緯度経度
categories ベニューが所属するカテゴリ(複数ある場合やゼロの場合もある)
verified ベニューのオーナーによって認証された情報かどうか
stats 総チェックイン数、今までにチェックインしたユーザー数、投稿されたTipsの数
hereNow 今チェックインしているユーザ数。認証ありの場合は、チェックイン中のユーザがフレンドかどうかもわかる

他にもいろいろな情報が取得できます。

ベニュー詳細

カテゴリ一覧取得

リソース

イケてるライブラリたち

フォーラム

公式開発ブログ

参考リンク

koogawa
ドラムも叩けるプログラマです。iPhoneアプリ、Androidアプリ、mixiアプリを仕事/趣味で作ってます。主な作品 → http://bit.ly/koogawa
http://d.hatena.ne.jp/koogawa/
alu-inc
アルは、マンガファンがもっとマンガを楽しめるサービスを作るために立ち上げられた、テクノロジー企業です。
https://alu.jp
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away