目次


foursquare API の紹介

PHP を使って基本的なアプリケーションを作成する

Comments

foursquare を始めとするロケーション・ベースのサービスが大流行しています。まだそうしたサービスについて聞いたことがない人も、間もなく耳にすることになるでしょう。foursquare や Gowalla、Loopt、その他のロケーション・ベースのサービスを提供するツールは至るところで使われており、お気に入りの場所に「チェックイン (Check in)」したり、好きな飲み物や料理に関するちょっとした情報を他のユーザーと共有したり、またそうした行動を Twitter や Facebook などの他のサービスで共有したりしています。

皆さんは開発者として、これらのサービスについて知っておく必要があります。ソーシャル・サービス、中でもソーシャル・プラットフォームを使用するロケーション・ベースのサービスは、Web 開発者やモバイル開発者にとって巨大な成長分野です。これらのサービスの大半は、何らかの RESTful なサービスを使用して JSON (JavaScript Serialized Object Notation) データまたは XML データをリクエストします。Facebook など一部のサービスでは、あまり認証が要求されませんが、foursquare などのサービスには、認証を必要とするフィードと認証を必要としないフィードがあります。

この記事では、ある程度読者が PHP について理解していることを前提にしますが、前提はそれだけです。PHP 以外のすべて、つまり foursquare のフィードへのアクセス、結果セットの処理、そして最終的な仕上げに関しては、ゆっくりと説明します。記事の最後で作成するサンプル・アプリケーションは単純です。このアプリケーションでは、foursquare に geolat 座標と geolong 座標を渡し、その座標が表す地点の近くの場所 (venue) に現在チェックインしている人の数を調べます。私はテキサス州オースティン (Austin, Texas) に住んでいるので、Sixth Street (6 番街) にある特定の場所の座標を入力し、その近くで何が起きているかを調べてみたいと思います。

私がこの具体的なアプリケーションを選択した理由は 2 つあります。第 1 の理由は、このフィードはアクセス対象として最も単純ですが、このフィードを解析してみると、他のフィードによってどんなことができるのか、その概要を非常によく理解することができます。第 2 の理由は、認証が必要ないことです。つまり、ここでは実際に誰がチェックインしているかの詳細を知りたいわけではなく、単に人数を知りたいにすぎません。この記事の目的に対し、venues 公開フィードを利用すると、非常に多くの機能を実現することができます。

foursquare とは何か

foursquare はユーザーが自分の周りの世界を探検できるソーシャル・ロケーション・サービスです。ユーザーは foursquare アプリケーションを iPhone や Blackberry、あるいは Android 搭載の携帯電話にダウンロードして無料でサインアップすることができます。そして自分の foursquare アカウントを他のソーシャル・メディアのアカウントに接続することができます。

ユーザーは、無料のアプリケーションをダウンロードして Facebook や Twitter に接続すると、同じく foursquare でアクティブな友達に接続することができます。ユーザーが、あるいはユーザーの友達が、ある場所 (venue) にチェックインすると (つまり、ある場所に彼らがおり、その場所にいることを他の人達に伝えると)、そのメッセージが Twitter や Facebook を介してブロードキャストされます。

ユーザーは、十分な回数のチェックインをすると、その場所 (venue) の長である mayor になります。mayor になると、その場所 (venue) で営業しているビジネスによってはスペシャル・オファーを受けられることがあります。例えば、あるコーヒー・ショップは mayor になった人全員に無料の飲み物をサービスしてくれるかもしれません。またユーザーは、特定の場所 (venue) を探検してチェックインするとバッジ (Badges) を獲得することもでき、他のユーザーのためにコメント (Tips) を残すことができます (例えば、「この店のマルガリータは素晴らしい!」など)。さらには、まだサービスに登録されていない場所を venue として作成することさえできます。

図 1 は Web 上にある foursquare のホームページのスクリーンショットです。

図 1. foursquare のホームページ
この画像は foursquare のホームページのスクリーンショットです。このホームページには、メニュー・オプション、ダウンロード・オプション、最近レポートされたアクティビティーが表示されています。
この画像は foursquare のホームページのスクリーンショットです。このホームページには、メニュー・オプション、ダウンロード・オプション、最近レポートされたアクティビティーが表示されています。

foursquare は 2009年 11月に API を公開し、アプリケーション開発者が foursquare プラットフォームを興味深い方法で拡張できるようにしました。これにより、開発者は、場所 (venue) を管理するツールやカスタムの検索エンジン、さらには foursquare API を使用するゲームおよびその他のツールまで作成することができます。例えば、プレイヤーが普通にゲームをするなかでごく当たり前に foursquare の場所 (venue) にチェックインできるようなジオロケーション・ゲームを作成することもできます。

こうした foursquare の概要を頭に入れた上で、foursquare API について調べてみましょう。

foursquare API の概要

アプリケーションは foursquare API を利用することで、foursquare プラットフォームを操作することができます。foursquare API そのものは、リクエストの送信先となる一連の RESTful なアドレスです。そのため、この API を利用するためにサーバーにダウンロードするようなものは何もありません。とは言え、この記事ではリクエストとレスポンスを単純化するために一連の PHP ライブラリーを使用しますが、それは完全にオプションのステップです。

現状では、出力を XML フォーマットまたは JSON フォーマットでリクエストします。そのため、http://api.foursquare.com/v1/user.json のような形で URL にリクエストを行います。リクエストに拡張子を指定しない場合には、XML が返されます。例えば http://api.foursquare.com/v1/user に対してリクエストを行うと、XML 出力が得られます。

使用できるメソッドには GETPOST の両方があります。つまり API を使用することで、単にフィードから読み取るだけではなく、どこかの場所 (venue) へのチェックインや場所 (venue) の作成など、実用的なこともすることができます。アクセス頻度の制限として、アプリケーションから発行できるリクエストの回数は 1 時間 1 メソッド当たり 200 回に制限されています。そこで、「節度ある動作」にするためには、おそらく何らかの形で結果のキャッシングを実装する必要があるでしょう。

ほとんどの場合、さまざまなメソッドやサービスをフルに活用するためには、Basic 認証または OAuth 認証を使う必要があります。この記事で紹介する例 (/venues) は、認証なしに使い始めることができますが、認証を必ず使用する人のために、追加の機能も備えています。

foursquare API によって何ができるのでしょう。表 1 は主なメソッドをまとめたものです。詳細については、API のドキュメントを読んでください (「参考文献」を参照)。

表 1. foursquare API のメソッドの要約
メソッド概要URLパラメーターHTTP メソッド認証
チェックイン情報の取得最近友達が行ったチェックインのリストを返しますhttp://api.foursquare.com/v1/checkinsgeolat、geolongGET必要
チェックインの実行ある場所 (venue) にチェックインすることができますhttp://api.foursquare.com/v1/checkinvid、venue、geolat、geolong (その他)POST必要
チェックイン履歴の取得認証されたユーザーがチェックインした場所のリストを返しますhttp://api.foursquare.com/v1/historyl、sinceidGET必要
ユーザーの詳細情報の取得指定されたユーザー ID に対するプロファイル情報を返しますhttp://api.foursquare.com/v1/useruid、twitter、badges、mayorGET必要
友達リストの取得友達のリストを返しますhttp://api.foursquare.com/v1/friendsuidGET必要
venue リストの取得指定されたエリア近郊の venue のリストを返しますhttp://api.foursquare.com/v1/venuesgeolat、geolong、l、qGET不要
venue の詳細情報の取得指定された ID の venue のデータを返しますhttp://api.foursquare.com/v1/venuevidGET不要
カテゴリー・リストの取得階層構造で表現されたカテゴリー・リストを返しますhttp://api.foursquare.com/v1/categoriesなしGET不要
venue の追加venue を追加しますhttp://api.foursquare.com/v1/addvenuename、address、city、state、zip、phone、geolat、geolong、その他POST必要
venue の編集編集や更新用に、ある venue にフラグを立てることができますhttp://api.foursquare.com/v1/venue/proposeeditvid、name、address、city、state、zip、phone、geolat、geolong、その他POST必要

他にも、友達に関するメソッド、認証をテストするためのメソッド、さまざまな理由から特定の場所にフラグを立てるためのメソッド、コメントの収集や作成のためのメソッドなど、非常に多数の API メソッドがありますが、上の表からおおよそどのようなものかを理解できると思います。

独自の PHP アプリケーションを作成する

ここまでで、foursquare API の概要を説明したので、今度は本題に入り、単純なアプリケーションを作成します。この記事の冒頭の部分で触れたように、このアプリケーションの目的は、オースティンの 6 番街のバーを中心とする場所 (venue) にチェックインした人の数を表示するビューを作成することです。しかし、わざわざ車でダウンタウンまで来て駐車スペースを見つけても、実際そこに誰もいなかったら、まったく意味がありません。

この目的のためには foursquare API を使うのは馬鹿げていると思えるかもしれませんが、この基本的な考え方をさまざまな状況で利用できることに注意してください。例えば、カンファレンスの出席者が街にいる間、出席者のうち何名がその街の venue にチェックインしているのか、あるいは何名がさまざまな分科会セッションにチェックインしているのかを追跡したりすることができます。

この記事では、このアプリケーションのプロセスを以下の 3 つの主な部分に分解します。

  1. ヘルパー・ライブラリーをダウンロードする
  2. 基本的なフィードを作成する
  3. 整理された Web ページを作成し、フィードの内容を表示する

foursquare-async ライブラリーをダウンロードする

実際には foursquare API のラッパーはそれほど必要ありませんが、素晴らしい foursquare-async ライブラリーを GitHub からダウンロードしてみるのも悪くありません (「参考文献」を参照)。このライブラリーをファイルのハンドルとして使用することで、foursquare API のメソッドのほとんどを扱うことができます。

ダウンロードの中には、readme ファイルとライセンス文書、そして以下の 3 つの PHP ファイルが含まれています。

  • EpiCurl.php
  • Epifoursquare.php
  • EpiOAuth.php

この 3 つの PHP ファイルをすべて、プロジェクトのルートにある lib というディレクトリーに配置し、アプリケーション作成の次のステップに進みます。

フィードを作成する

次は、feed.php というファイルを作成し、プロジェクトのルートに配置します。このファイルでは、ダウンロードしたすべての Epi*.php ファイルを取り込んで lib フォルダーに配置するために require() 関数を使用します。

続いて、新規 epiFourSquare オブジェクトをインスタンス化し、このオブジェクトを使って venues.json フィードに接続し、geolat および geolong として必要な引数と、1 ページあたりに表示する結果の制限としての 50 を渡します。

最後に、受信した JSON フィードを json_encode() を使って PHP データ・オブジェクトに変換し、配列として保存します。もちろん、確実を期すために、全体を try {...}exception の中にラップします。

json_encode() を使ってフィードを実行しないと、以下のようなフィードを処理する羽目になります。

図 2. そのままの JSON フィード
この画像はそのままの JSON フィードを表しており、フォーマット設定されていないテキストとしてコードが表示されています。
この画像はそのままの JSON フィードを表しており、フォーマット設定されていないテキストとしてコードが表示されています。

一部の人はこれでも構わないかもしれませんが、図 3 のような PHP データ・オブジェクトの方が多少理解しやすいことは認めざるを得ないはずです。

図 3. JSON から得られた PHP データ・オブジェクト
この画像は JSON から得られた PHP データ・オブジェクトを示しており、コードは読みやすくフォーマット設定されています。
この画像は JSON から得られた PHP データ・オブジェクトを示しており、コードは読みやすくフォーマット設定されています。

リスト 1 はコードの全体です。

リスト 1. foursquare の venues フィードに接続する
require('lib/EpiCurl.php');
require('lib/EpiOAuth.php');
require('lib/EpiFoursquare.php');

$fsObj = new EpiFoursquare();
try{
	$venues = $fsObj->get_basic('/venues.json', 
			array('geolat' => '30.268056',
			'geolong' => '-97.741381',
			'l' => '50'));
			
	$venues_array = json_decode($venues->responseText);
		
}catch(Exception $e){
	echo "Error: ". $e;
}

これはそれほど複雑なものではなく、venues フィードとチェックインのカウント値を取得するための 15 行のコードにすぎません。この例の geolat 座標と geolong 座標は、オースティンのダウンタウンにある Driskill ホテルの近くを表しています。この場所を選択した理由は、その近くにはダウンタウンの venue が数多く登録されているため、中心地点として都合が良いからです。

Web のビューを作成する

この段階で得られたものは、PHP データ・オブジェクトに変換された JSON フィードです。これは PHP プログラマーにとっては便利ですが、他の人にはほとんど使い道がありません。実際には、誰もが使用できるように、この PHP データ・オブジェクトを Web ページとして構成する必要があります。

そのためには、ディレクトリーのルートに index.php ファイルを作成します。CSS (Cascading Style Sheets) と JavaScript フレームワーク、そして設計要素としては、皆さんが使い慣れたものを使用することができます。例えば、リスト 2 に示すサンプル・コードでは 960 Grid フレームワークを使っています。その理由は、このフレームワークを使うことで作業が楽になるからです。また、先ほど作成した feed.php コードを含めるのに続いて、データ・テーブルに収まるように $venues_array 配列の処理をします。

厄介なのは、foursquare API が階層構造をしており、最初のレベル (groups) はほとんど意味がないところです。後で使用する貴重な情報を抽出するループ処理を行うのは venues レベルなので、venues レベルにアクセスする必要があります。

サンプルの一部を抜粋したリスト 2 は、その概略を示しています。PHP データ・オブジェクトの適切な場所で、foreach ($venues_array->groups[0]->venues as $v){ によってループが開始されます。このループにより、$v->name (venue の名前) や $v->stats->herenow (その venue に現在チェックインしている人の数) などにアクセスしています。

実際、ループを通過するごとに $v のデータ構造を視覚化してみると、その構造はリスト 2 のようなものになります。

リスト 2. 各 venue に対する PHP データ・オブジェクト
stdClass Object
{
    [id] => 5261
    [name] => Driskill Hotel
    [primarycategory] => stdClass Object
        {
            [id] => 79273
            [fullpathname] => Travel:Hotel
            [nodename] => Hotel
            [iconurl] => http://foursquare.com/img/categories/travel/hotel.png
        }

    [address] => 604 Brazos St
    [crossstreet] => at W 6th St
    [city] => Austin
    [state] => TX
    [zip] => 78701
    [geolat] => 30.2679601
    [geolong] => -97.7413707
    [stats] => stdClass Object
        {
            [herenow] => 0
        }
    
    [phone] => 5124745911
    [distance] => 0
}

リスト 3 のコード・スニペットは index.php ページ全体を示しています。この中で、データ構造に対してループ処理を行い、必要なデータを抽出して $final 配列に追加し、そして $final 配列を使ってデータ・テーブルを作成しています。その結果としてダッシュボードが得られ、venue の名前、住所と電話番号、そこに現在チェックインしている人の数がダッシュボードに表示されます。

また、電話番号は venue に関する必須フィールドではないため、電話番号がデータ・フィードに含まれているかどうかの簡単なチェックを行い、電話番号が含まれている場合には電話番号を出力し、含まれていない場合には省略するようにします。

リスト 3. index.php ビューを作成する
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
    <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
    <title>FourSquare API Test</title>
    <link rel="stylesheet" type="text/css" href="css/960.css" media="all" />
    <link rel="stylesheet" type="text/css" href="css/reset.css" media="all" />
    <link rel="stylesheet" type="text/css" href="css/text.css" media="all" />
    <link rel="stylesheet" type="text/css" href="css/tables.css" media="all" />


</head>
<body>
	 <div class="container_12">
	 	<div class="grid_12">
	 	<h1>FourSquare API Test</h1>
	 	</div>
	 </div>


	 <div class="container_12">
	 	<div class="grid_12" id="updates">
	 	<?php
		include_once 'feed.php'; 
	 	$final = array();
	 	
	 	foreach ($venues_array->groups[0]->venues as $v){
	 		if (isset($v->phone)){
	 			$PHONE = $v->phone;
	 		}else{
	 			$PHONE = "not listed";
	 		}
	 		
	 		$final[$v->id] = array(
	 						'name' => $v->name, 
	 						'address' => $v->address, 
	 						'herenow' => $v->stats->herenow,
	 						'phone' => $PHONE
	 						);
	 	
	 	}
	 	
	 	?>
	 	
	 	<table border='1' cellspacing='0' cellpadding='0'>
	 	<thead>
	 		<tr valign='top'>
	 		<th>Location</th>
	 		<th>Address</th>
	 		<th>Phone</th>
	 		<th>Here Now</th>
	 		</tr>
	 	</thead>
	 	<tbody>
	 	<?php
	 	foreach ($final as $key => $data){
	 		echo "<tr valign='top'>";
	 		echo "<td>".$data['name']."</td>\n";
	 		echo "<td>". $data['address']."</td>\n";
	 		echo "<td>". $data['phone']."</td>\n";
	 		echo "<td align='center'>". $data['herenow']."</td>\n";
	 		echo "</tr>\n";
	 	}
	 	?>
	 	</tbody>
	 	</table>
	 	
	 	</div>
	 </div>
</body>
</html>

コード・サンプルのうち、PHP 以外の大部分は単に見栄えを良くするためのものであり、必ずしも機能上必要なものではありません。情報を視覚に訴えるものにするために、独自のスタイルや手法を適用することもできます。例えば、PHP ファイルから得られた JSON フィードを jQuery.getJSON() メソッドに結びつけ、Web ページを更新しなくても JSON フィードが更新されるようにする方法があります。

また、より単純で簡潔なリストとして情報を表現できるようにし、スマートフォンの小さな画面でもより自然に表示されるようにすることもできます。例えば、リスト 4 はリストを生成する最終的な foreach ループを示しています。

リスト 4. リストを単純化する
	 	?>
	 	
	 	<ul>
	 	<?php
	 	foreach ($final as $key => $data){
	 		echo "<li>";
	 		echo $data['name']." (". $data['herenow'].")". "<br/>\n";
	 		echo $data['address']."<br/>\n";
	 		echo $data['phone']."<br/>\n";
	 		echo "</li>\n";
	 	}
	 	?>
	 	</ul>

単純に UL ノードと LI ノードにクラスをいくつか追加するだけで、iPhone やその他のモバイル機器のユーザーにとって極めて見やすい効果的な表示にすることができます。それらのユーザーは、Web ページをチェックして特定の geolat/geolong 座標の周囲の場所で何が起きているのかを調べ、その晩どこに行くかを決めることができます。

ユーザー・エクスペリエンスを改善するために、他にどんなことができるでしょう。foursquare でユーザーの認証を要求し、認証されたユーザーに詳細な情報を表示することができます。この記事では認証の方法については説明しませんが、ユーザーを認証できると、リストに含まれている特定の友達に関する追加の情報を表示することができます。また、単純な地図インターフェースを提供し、最初にユーザーが geolat/geolong 座標を選択できるようにし、より汎用的で使い道のあるツールにすることもできます。

まとめ

これで foursquare API の使い方を理解できたので、今度は何か面白いものを作成してみてください。ただし、深入りする前に、この API を使って他の人達が何をしているのかをよく調べてみてください。foursquare の App Gallery には、他の人達が作成した、注目に値するアプリケーションがいくつか含まれています (「参考文献」を参照)。


ダウンロード可能なリソース


関連トピック


コメント

コメントを登録するにはサインインあるいは登録してください。

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=Open source
ArticleID=594578
ArticleTitle=foursquare API の紹介
publish-date=11092010