foursquare api その２：API利用まで
前回に続き4sq api。
前提
これから、foursquare apiを使って、場所情報を取得します。
foursquareのアカウントを持ってないと出来ないので、
アカウントを持ってない方は作って下さい。
※右上の「登録する」ボタンから指示通りアカウントを作成して下さい。
APIのページ
foursquareにログインして、TOPページの右下に
「開発者 独自のアプリをつくる」というリンクがあるので
これをクリックして、開発者用のページに遷移して下さい。
(2012/12/22現在。)
開発者ページ
開発者向けのページに行ったら、「My Apps」リンクを押して、
マイアプリページに行って下さい。
そこで、「新しいアプリをつくる」をクリック。
アプリ登録画面
色々ありますが、とりあえず、必須項目だけ埋めます。。
アプリのタイトル：first_app
ウェルカムページ：http://www.google.co.jp
コールバックURL：http://www.google.co.jp
※今回、特にuser login等作らないので、上記URLは何でも大丈夫です。
これで保存すると、このアプリの情報が表示されるようになります。
Client idとClient secretが発行されていれば、終了です。
APIにアクセス
早速、アクセスしてみませう。
とりあえず、今回は、場所検索のAPIを叩く
https://developer.foursquare.com/docs/venues/search
①場所情報として渋谷(緯度：35.658517 軽度：139.701334)
②キーワードとしてcafe
（URLエンコードすると、分かり辛くなるため、あえて英語にしてますが、日本語も指定可能です。）
を渡して、スポット情報を取得する所までやってみる。
ドキュメントの読み方
初めて見る方の為に概説。
- 一覧
https://developer.foursquare.com/docs/
ここに、APIの一覧があり、ここから、やりたい事を見つける
- 詳細
https://developer.foursquare.com/docs/venues/search
ホスト〜パスまでは、上記ページに記載してるものを使う。
※タイトル下のオレンジ色のURL
初めの解説の後、表形式で、Requires Acting Userとあるのは、
ユーザー情報の必要有無で、必要であれば、パラメータ指定が必要。
※今回は、Noなので、指定しない。
urlの組み立て
このURLのCLIENT_IDとCLIENT_SECRETに、
先ほどの開発者向けのページで作ったアプリの
client id / client secret を貼付けるて、
ブラウザのURLに入れてみると、スポット情報のjsonが取れるはず。
パラメータ:ll
以下、リクエストに付与するクエリストリング、パラメータについて。
詳細ページ見ると、llとnearのいずれかが必須と書いてある。
- llは、緯度、軽度の事。
- nearは、地名の事。
このいずれかを使って、場所を指定する。
今回は、渋谷の緯度経度が分かっているので、llを使う。
＜注意＞
ちなみに、nearは、geocodeで地名から緯度経度を調べますが、
この地名が正確さを求められており、表記の揺れを吸収してくれません。
例えば、
- near=吉祥寺はレスポンスが正しく返ってくるのに、
- near=渋谷はレスポンスがerrorメッセージをはきます。
{"meta":{"code":400,"errorType":"failed_geocode","errorDetail":"Couldn't geocode param near: 渋谷"},"response":{}}
おそらく、吉祥寺は駅名しかないのに対して、
渋谷は、渋谷駅と渋谷区と複数ひっかかるため、判断できないのでしょう。
なので、near=渋谷駅と書くと、正常に取得できます。
渋谷は、分かり易い例なのですが、
例えば、田町のように、県をまたがって複数候補がある場合は、
田町の後にごちゃごちゃ記述が必要だったりして、結構面倒臭いです。
なので、地名の文字からfoursquareのAPIをたたく際は、
そのままパラメータを渡すのではなく、
別のAPIで複数の場所の候補を取得できてuserに選択させる、
といった対応をした方がいいでしょう。
パラメータ:query
queryは、場所を検索するためのキーワード。
今回は、カフェを指定。
パラメータ:v
vというパラメータは、後方互換のためのパラメータ。
foursquareも色々、改修を加えており、いつ、実装が変わるか分からない。
そんな中、ある時点でのソースでレスポンスを返し続けるために
準備されているもの。
但し、あまりに古いversionになると、
response codeは200を返して、結果も正常に出力するが、
以下のようなerrorメッセージもはくとの事。
※２年前のvを指定してみて、得られた結果。
{"meta":{"code":200,"errorType":"deprecated","errorDetail":"This endpoint will stop returning groups in the future. Please use a current version, see http:\/\/bit.ly\/vywCav."},
...(エラーメッセージありますが、この後、正常な結果がつきます。)
とりあえず、今日の日付を入れておく。
※この日付はいつでもOKで、コミットタイミングに合わせる必要は無い。
レスポンス
こんなレスポンスを得られているはず。
{
"meta": {
"code": 200
},
"response": {
"venues": [
{
"canonicalUrl": "https://foursquare.com/v/craightons-cafe/***********************",
"categories": [
{
"icon": {
"prefix": "https://foursquare.com/img/categories_v2/food/cafe_",
"suffix": ".png"
},
"id": "*******************************",
"name": "カフェ",
"pluralName": "カフェ / 喫茶店",
"primary": true,
"shortName": "カフェ"
}
],
"contact": {
"formattedPhone": "+81 *-****-****",
"phone": "+*************"
},
"hereNow": {
"count": 0,
"groups":
},
"id": "**************************",
"likes": {
"count": 0,
"groups":
},
"location": {
"address": "渋谷*-**-*",
"cc": "JP",
"city": "渋谷区",
"country": "Japan",
"distance": 57,
"lat": 35.*************,
"lng": 139.**************,
"state": "東京都"
},
"name": "************* Cafe",
"referralId": "v-**************",
"restricted": true,
"specials": {
"count": 0,
"items": []
},
"stats": {
"checkinsCount": 264,
"tipCount": 1,
"usersCount": 211
},
"verified": false
},・・・その他、venue(場所)情報
注意
以外と、電話や住所がないスポット情報多いので、注意。
