WOEIDを取得する方法 (Yahoo! API)

WOEIDを取得する方法 (Yahoo! API)

1つ1つの「場所」に識別子となるIDを付けるWOEID。Yahoo!のチームが立ち上げたこのプロジェクトは、まだまだ日本では認知度が低い気もしますが、普及したら物凄く便利ですよね。ちなみにTwitterも、トレンドワード・システムの地域分けにWOEIDを利用しています。今回は、海外のYAHOO!COMのAPIを利用して、このWOEIDを調べる方法を説明します。

WOEIDとは何か?

WOEIDとは、場所に識別子を付けたデータベースです。都道府県単位、市区町村単位に止まらず、公園、観光スポット、駅など、その対象は様々です。IDを紐付けることによって、全く関係のない異なるどのアプリケーションでも、同じ場所を正確に取り扱えるという利点があります。大きなサービスで言えば、Twitterが、場所の管理にWOEIDを利用しています。

例えば、私が大好きな地元、足立区の「竹ノ塚駅」のWOEIDのデータは下記の通りです。住所はないものの、かなり細かいデータを取得できるのが分かると思います。位置座標だけではなく、範囲(左下端と右上端の座標)を表すboundingBoxまで取得できるのは便利ですよね。

WOEID22333221
名称竹ノ塚駅
所属国日本
地域レベル1東京都
地域レベル2足立区
地域レベル3西竹の塚
郵便番号121-0822
言語日本語
タイムゾーンAsia/Tokyo
緯度35.79443
経度139.790771
範囲(南西)35.79398,139.790207
範囲(北東)35.79488,139.791336

準備(APIキーの取得)

WOEIDに限らず、海外のYahoo.comが提供する様々なAPIを利用するには、アプリケーションを作成し、APIキーを取得して下さい。この章では、その手順を説明します。

ユーザーアカウントの取得

Yahoo.comのユーザーアカウントを既に所有している人は、この項目は読み飛ばしていただいて大丈夫です。

ユーザーアカウントの作成

Yahoo.com
Yahoo.com

まずは、海外のYahoo.comのユーザーアカウントを取得して下さい。Yahoo.comには、下記ページからアクセスすることができます。

「Sign In」をクリックする
「Sign In」をクリックする

Yahoo.comにアクセスしたら、「Sign In」という項目をクリックして下さい。

「Create Account」をクリックする
「Create Account」をクリックする

ログイン画面に移動します。アカウントを新規作成するために、「Create Account」をクリックして下さい。

ユーザー情報を入力する
ユーザー情報を入力する

図を参考に、ユーザー情報を入力し、「Create account」のボタンをクリックします。電話番号は、携帯電話だったら090から、ハイフンなしの入力で大丈夫です。「Optional recovery number」の欄は無視して大丈夫です。

Verification
Verification

最後に、人間の操作だと証明するための、Verificationを入力します。このシステムがこの世からなくなることを願っている毎日です。

アカウントが作成される
アカウントが作成される

入力内容に問題がなければ、ユーザーアカウントの作成が完了します。

本人認証

My Yahooにアクセスする
My Yahooにアクセスする

アプリケーションを作成する時に、電話番号、またはメールアドレスでの本人認証を要求されるかもしれません。そうなった時のために、認証方法を説明しておきます。ログイン後、Yahoo.comのトップページにあるアカウント名をクリックして下さい。

Securityの項目
Securityの項目

アカウントの設定画面に移動します。ページ左側にあるメニューの中から「Security」をクリックして下さい。「Phone numbers」、または「Email addresses」で、本人認証の作業をすることができます。もし求められたら、作業をして下さいね。

アプリケーションの作成

Yahoo.comのユーザーアカウントを作成後、いよいよ、アプリケーションを作成していきましょう。といっても作業は簡単でした。まずは、Yahoo! Developers Networkにアクセスして下さい。

利用規約に同意する
利用規約に同意する

初回アクセス時、利用規約への同意を求められます。よろしければ、「Accept」をクリックして下さい。上の吹き出しはどうしても消えなかったものです…。こういうUIは鬱陶しいものですね。

「Create an App」をクリックする
「Create an App」をクリックする

Yahoo! Developers Networkの「My App」のページに移動します。ここには、あなたが作成したアプリケーションの一覧が表示されます。作成していない場合は、まだ何も表示されていないはずです。「You currently have no apps.」となっていますね。アプリケーションを作成するには「Create an App」のボタンをクリックして下さい。

アプリケーションの情報を入力する
アプリケーションの情報を入力する

アプリケーションの情報を入力するフォームに移動します。図を参考に、情報を入力し、最後に「Create App」のボタンをクリックして下さい。注意点として、「Application Type」はウェブで利用するなら「Web-based」を選択します。「Access Scoped」ですが、認証を経て特定ユーザーのプライベートな情報を取得するなら下を、認証を経ないで公的な情報を取得するなら上を選択して下さい。日本で海外ヤフーユーザー向けのサービスは作る機会がないと思うので、私は上を選択しました。また、「Premium API service」も必要ないでしょう。

アプリケーションの情報を確認する
アプリケーションの情報を確認する

入力に問題がなければ、アプリケーションが作成され、そのまま、アプリケーションの詳細画面に移動します。「Authentication Infomation」というメニュー内に「Consumer Key」と「Consumer Secret」という項目があります。これが、それぞれ、API Key、Secret Keyとなります。お疲れ様でした。

APIキーが有効か確認してみる

APIキーを確認してみましょう。例えば、WOEIDというコードを取得するためのAPIを、取得したキーを利用して試してみて下さい。下記URLにアクセスして、しっかりとデータを取得できたなら、成功です。もし取得できない場合は、コピーを間違えているか、違うコードと勘違いしている可能性があります。

http://where.yahooapis.com/v1/places.q(%E4%BA%AC%E9%83%BD%E5%BA%9C)?appid={取得したAPIキー} リンク

アプリケーションの詳細画面

My Appにアプリケーションが加わる
My Appにアプリケーションが加わる

先ほどの、Yahoo! Developers Networkにアクセスすると、今作成したアプリケーションが一覧に加わっています。このアプリケーション名をクリックすると、前述の詳細画面に移動することができます。キーを確認したい時などは、この手順でアクセスしましょう。

アプリケーションを削除する

アプリケーションを削除する
アプリケーションを削除する

もし、キーが他人に知られてしまったりして、アプリケーションを削除する必要がある場合は、詳細画面にある「Delete App」というリンクから実行することができます。アプリケーションを削除した場合、当然ながら、APIキーも無効になってしまうので、ご注意下さい。

WOEIDを取得する方法

YAHOO.COMのAPIキーを入手したら、早速、WOEIDを取得してみましょう。「地名から取得する」「WOEIDを指定して取得する」など様々な取得方法がありますが、何も情報がない状態の初めは、地名から取得するのが一般的だと思います。

リクエスト方法

下記のエンドポイントにGETメソッドのリクエストを送って下さい。地名は日本語でも大丈夫ですが、URLエンコードをして下さいね。

GET http://where.yahooapis.com/v1/places.q({地名})?appid={取得したAPIキー}

パラメータ

appid
APIキー。
lang
言語コードを「RFC 4646」の規格で指定する。日本の場合はja-JP
format
レスポンスデータのフォーマットを指定する。デフォルトはxml
xml … XML
json … JSON
geojson … GeoJSON
callback
コールバック用関数名。フォーマットがJSON、またはGeoJSONの場合にのみ有効。
view
レスポンスデータの内容を、詳しいものにするか、それともシンプルなものにするかを指定する。
short … シンプル
long … 詳細

取得できるJSON

APIのリクエストで取得できるデータのサンプルです。フォーマットは、JSONです。パラメータのviewに、shortlongを指定した場合で、内容量が違います。longshortを全て含みます。

short

JSON

{"places":{"place":[{"woeid":22333221,"placeTypeName":"WOE_POI","placeTypeName attrs":{"code":20},"name":"\u7af9\u30ce\u585a\u99c5","uri":"http:\/\/where.yahooapis.com\/v1\/place\/22333221","lang":"ja"}],"start":0,"count":1,"total":1}}

long

JSON

{"places":{"place":[{"woeid":22333221,"placeTypeName":"WOE_POI","placeTypeName attrs":{"code":20},"name":"\u7af9\u30ce\u585a\u99c5","country":"\u65e5\u672c","country attrs":{"type":"WOE_COUNTRY","code":"JP","woeid":23424856},"admin1":"\u6771\u4eac\u90fd","admin1 attrs":{"type":"\u90fd\u9053\u5e9c\u770c","code":"","woeid":2345889},"admin2":"\u8db3\u7acb\u533a","admin2 attrs":{"type":"Gun\/Ku","code":"","woeid":1118608},"admin3":"\u897f\u7af9\u306e\u585a","admin3 attrs":{"type":"WOE_LOCALADMIN","code":"","woeid":28414709},"locality1":"\u6771\u4eac","locality1 attrs":{"type":"WOE_TOWN","woeid":1118370},"locality2":"","postal":"121-0822","postal attrs":{"type":"WOE_ZIP","woeid":26237386},"centroid":{"latitude":35.79443,"longitude":139.790771},"boundingBox":{"southWest":{"latitude":35.79398,"longitude":139.790207},"northEast":{"latitude":35.79488,"longitude":139.791336}},"areaRank":0,"popRank":0,"timezone":"Asia\/Tokyo","timezone attrs":{"type":"WOE_TIMEZONE","woeid":28350861},"uri":"http:\/\/where.yahooapis.com\/v1\/place\/22333221","lang":"ja"}],"start":0,"count":1,"total":1}}

各プロパティの説明

JSONデータの各項目が何を示しているかを説明します。値がコードで示されているもの(areaRankなど)については、次章と照らし合わせて下さい。

woeid
「場所」のWOEID。
placeTypeName
「場所の種類」を表すコードの識別値(名称)。
placeTypeName attrs->code
「場所の種類」を表すコードの識別値(数字)。各数字が何を表すかは次章を参照。
name
「場所」の名称。
country
所属している国。
admin1
所属している地域の最上位。日本で言えば、都道府県にあたる。
admin2、admin3、locality1、locality2
所属している地域。日本で言えば、市区町村以下にあたる。場所によって、かなり曖昧になっている。例えば、東京都の「足立区」はadmin2だが、栃木県の「日光市」はadmin3になる。一律した処理を実装する時は、広くケースをフォローする必要がある。
postal
郵便番号。
centroid
位置座標。緯度と経度。
boundingBox
「場所」の範囲を表す、北東(右上端)と南西(左下端)の位置座標。
areaRank
面積の大きさを表すランク。各ランクがどれくらいの規模を表すかは次章を参照。
popRank
人口の多さを表すランク。各ランクがどれくらいの規模を表すかは次章を参照。
timezone
タイムゾーン。
lang
言語。
url
この「場所」のWOEIDデータを取得するための、APIのエンドポイントURL。当然ながら、このURLに、APIキーのパラメータを付けないと取得できないので注意。
start
取得したデータの開始位置。
count
取得した件数。
total
トータル件数。

サンプルプログラム

下記がWOEIDを取得するための、サンプルプログラムです。

PHP

<?php

	// クライアントキー
	$consumer_key = '' ;

	// キーワード
	$keyword = '舎人公園' ;

	// パラメータ
	$params = array(
		'appid' => $consumer_key ,
		'lang' => 'ja-JP' ,
		'format' => 'json' ,
		'view' => 'long' ,
	) ;

	// リクエストURL
	$request_url = 'http://where.yahooapis.com/v1/places.q(' . rawurlencode( $keyword ) . ')' . '?' . http_build_query( $params ) ;		// リクエストURL

	// アイテムデータをJSON形式で取得する (CURLを使用)
	$curl = curl_init() ;

	// オプションのセット
	curl_setopt( $curl , CURLOPT_URL , $request_url ) ;
	curl_setopt( $curl , CURLOPT_HEADER, 1 ) ; 
	curl_setopt( $curl , CURLOPT_SSL_VERIFYPEER , false ) ;								// 証明書の検証を行わない
	curl_setopt( $curl , CURLOPT_RETURNTRANSFER , true ) ;								// curl_execの結果を文字列で返す
	curl_setopt( $curl , CURLOPT_TIMEOUT , 5 ) ;										// タイムアウトの秒数

	// 実行
	$res1 = curl_exec( $curl ) ;
	$res2 = curl_getinfo( $curl ) ;

	// 終了
	curl_close( $curl ) ;

	// 取得したデータ
	$json = substr( $res1, $res2['header_size'] ) ;										// 取得したデータ(JSONなど)
	$header = substr( $res1, 0, $res2['header_size'] ) ;								// レスポンスヘッダー (検証に利用したい場合にどうぞ)

	// HTML用
	$html = '' ;

	// JSONデータをオブジェクト形式に変換する
	$obj = json_decode( $json ) ;

	// HTMLを作成
	$html .= '<h2>実行結果</h2>' ;

	// エラー判定
	if( !$obj || !isset($obj->places->place) || empty($obj->places->place) )
	{
		$html .= '<p>データを取得できませんでした…。設定を再確認して下さい。</p>' ;
	}
	else
	{
		// HTML
		$html .= '<p>「<b>' . $keyword . '</b>」で検索したところ、合計で<b>' . count( $obj->places->place ) . '</b>件の場所がヒットしました。</p>' ;

		// 解析
		foreach( $obj->places->place as $item )
		{
			// 各データ
			$woeid = $item->woeid ;		// WOEID
			$name = $item->name ;		// 場所名
			$latitude = $item->centroid->latitude ;		// 緯度
			$longitude = $item->centroid->longitude ;		// 経度

			// 出力
			$html .= '<dl>' ;
			$html .= 	'<dt>場所名</dt>' ;
			$html .= 		'<dd>' . $name . '</dd>' ;
			$html .= 	'<dt>WOEID</dt>' ;
			$html .= 		'<dd>' . $woeid . '</dd>' ;
			$html .= 	'<dt>緯度</dt>' ;
			$html .= 		'<dd>' . $latitude . '</dd>' ;
			$html .= 	'<dt>経度</dt>' ;
			$html .= 		'<dd>' . $longitude . '</dd>' ;
			$html .= '</dl>' ;
		}
	}

	// 取得したデータ
	$html .= '<h2>取得したデータ</h2>' ;
	$html .= '<p>下記のデータを取得できました。</p>' ;
	$html .= 	'<h3>JSON</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $json . '</textarea></p>' ;
	$html .= 	'<h3>レスポンスヘッダー</h3>' ;
	$html .= 	'<p><textarea rows="8">' . $header . '</textarea></p>' ;

?>

<?php
	// ブラウザに[$html]を出力 (HTMLのヘッダーとフッターを付けましょう)
	echo $html ;
?>

このコードの動作を確認する

場所タイプ [placeType Code]

placeTypeName Codeは、「場所」の種類を示す数字の識別子です。各数字の内容は下記の通りとなっています。

7市、町、村。
8主要な管理エリア。
9二次の行政区域。
10三次の行政区域。
11郵便番号。
12ISO 3166-1で管理される国や属領。
13島。
14空港。
15川、運河、湖などの水関係の地域。
16公園、山、ビーチなど。
17未分類。
19複数の国を含むエリア。
20観光名所などのスポット。
22町を細分化したエリア。
24口語で知られているエリア。例えば「シリコンバレー」など。
25MSA(アメリカ合衆国大都市統計地域)など、特定の指標をもって区分けされたエリア。
26歴史的に主要な管理エリア。
27二次的な、歴史的に主要な管理エリア。
297つの大陸。「アフリカ」「ヨーロッパ」「南アメリカ」「南極大陸」「アジア」「北アメリカ」「オーストラリア大陸」。
31タイムゾーンで管理されたエリア。例えば「Asia/Tokyo」など。
33有名な住宅地、再開発地。
35旧行政区域。
375つの海。「大西洋」「南極海」「インド洋」「太平洋」「北極海」。
38規模の小さい海、湾岸など。「地中海」「アカバ湾」「イギリス海峡」など。

面積 [areaRank]

areaRankは、その「場所」の面積をランク付けしたデータです。各ランクの面積は下記の通りとなっています。

0不明。
11〜3km。
23〜10km。
310〜30km。
430〜100km。
5100〜300km。
6300〜1000km。
71,000〜3,000km。
83,000〜10,000km。
910,000〜30,000km。
1030,000〜100,000km。
11100,000〜300,000km。
12300,000〜1,000,000km。
131,000,000〜3,000,000km。
143,000,000〜10,000,000km。
1510,000,000〜30,000,000km。
1630,000,000〜100,000,000km。
17100,000,000〜300,000,000km。
18300,000,000〜1,000,000,000km。

人口 [popRank]

popRankは、その「場所」の人口をランク付けしたデータです。各ランクの人口は下記の通りとなっています。

0不明。
11〜3人。
23〜10人。
310〜30人。
430〜100人。
5100〜300人。
6300〜1000人。
71,000〜3,000人。
83,000〜10,000人。
910,000〜30,000人。
1030,000〜100,000人。
11100,000〜300,000人。
12300,000〜1,000,000人。
131,000,000〜3,000,000人。
143,000,000〜10,000,000人。
1510,000,000〜30,000,000人。
1630,000,000〜100,000,000人。
17100,000,000〜300,000,000人。
18300,000,000〜1,000,000,000人。
191,000,000,000〜3,000,000,000人。
203,000,000,000〜10,000,000,000人。

エンドポイント一覧

各エンドポイントと、その説明です。まず、下記がベースとなるエンドポイントのURLです。キーワード以外でWOEIDを指定したい場合にご利用下さい。

GET http://where.yahooapis.com/v1

以降のURLは、このベースに続けて下さい。当然ですが、加えてAPIキーなどのパラメータも必要です…。

/place/{woeid}
WOEIDを指定することで、そのWOEIDのデータを取得することができる。
/place/{woeid}/parent
WOEIDを指定することで、そのWOEIDの親(1つ上)にあたる場所の一覧を取得することができる。
/place/{woeid}/ancestors
WOEIDを指定することで、そのWOEIDの祖先となる場所の一覧を、ツリー式に取得することができる。
/place/{woeid}/belongtos
WOEIDを指定することで、そのWOEIDを含めている場所の一覧を取得することができる。
/place/{woeid}/neighbors
WOEIDを指定することで、そのWOEIDと同じ親を持つ場所の一覧を取得することができる。
/place/{woeid}/siblings
WOEIDを指定することで、そのWOEIDと同じ親と場所タイプを持つ場所の一覧を取得することができる。
/place/{woeid}/children
WOEIDを指定することで、そのWOEIDの子(1つ下)にあたる場所の一覧を取得することができる。
/place/{woeid}/descendants
WOEIDを指定することで、そのWOEIDの子孫となる場所の一覧を、ツリー式に取得することができる。日本だとあまり機能しない…。東京都を指定しても、取得件数は0となる。
/place/{woeid}/common/{woeid}
2種類のWOEIDを指定することで、両方の場所に共通する祖先にあたる場所を取得することができる。
/continents
大陸にあたる場所の一覧を取得することができる。
/oceans
大海にあたる場所の一覧を取得することができる。
/seas
海にあたる場所の一覧を取得することができる。
/seas/{place}
{place}に、大海の名称を指定することで、その大海に属する海の一覧を取得することができる。
/countries
国にあたる場所の一覧を取得することができる。
/countries/{place}
{place}に、大陸、または大海の名称を指定することで、それに属する国の一覧を取得することができる。
/states/{country}
{country}に、国名、または国コードを指定することで、その国に属するトップレベルの主要管理エリア(日本でいえば都道府県)の一覧を取得することができる。
/counties/{state}
{state}に、都道府県名を指定することで、その都道府県に属する主要管理エリア(日本でいえば市区町村)の一覧を取得することができる。
/districts/{counties}
{country}に、市区町村名を指定することで、その市区町村に属する三次レベルの管理エリア(日本でいえば市区町村以下)の一覧を取得することができる。
/admin1s/{country}
{country}に、国名、または国コードを指定することで、その国に属するadmin1の一覧を取得することができる。/states/{country}と同じ。
/admin2s/{admin1}
{state}に、都道府県名を指定することで、その都道府県に属する主要管理エリア(日本でいえば市区町村)の一覧を取得することができる。/states/{country}と同じ。
/admin3s/{admin2}
{country}に、市区町村名を指定することで、その市区町村に属する三次レベルの管理エリア(日本でいえば市区町村以下)の一覧を取得することができる。/districts/{counties}と同じ。
/placetypes
場所タイプの一覧を取得することができる。
/placetypes/{country}
国コードを指定することで、その国にローカライズした、場所タイプの一覧を取得することができる。
/placetype/{type}
場所タイプのコードを指定することで、その場所タイプの情報を取得することができる。
/placetype/{type}/{country}
国コードと場所タイプのコードを指定することで、その国にローカライズした、その場所タイプの情報を取得することができる。

ダウンロード

この記事で紹介したサンプルプログラムを配布しています。あなたのウェブサイトでぜひ、ご活用下さい。

ファイル一覧

SYNCER00297
get-woeid.php Download

ファイル名をクリックすると内容を確認できます。「Download Zip」をクリックするとファイル一式をダウンロードできます。

Download Zip