Bing Maps REST Services
前回 まではBing Map App SDKについて紹介してきました。今回からはBing Maps REST Servicesを使ってみましょう。Bing Maps REST Servicesは、ちょうど この連載が始まる時期に登場した新しいWeb APIで、このAPIを利用すると、地理情報の取得、Bing Mapsの地図を構成するタイル画像の取得、ルート探索などが可能です。
Bing Maps REST Servicesは次の3種類のAPIに分類されています。
Locations API
住所や経緯度、クエリーから地理情報を取得できるAPIです。
Imagery API
地図画像を取得、プッシュピンを配置した・ルート情報を表示した地図画像の取得、タイル画像のメタデータを取得できるAPIです。
Routes API
ルートの探索ができるAPIです。
これらのAPIでは、HTTPまたはHTTPSで特定のURLにアクセスし、結果をXMLまたはJSON形式で取得します。ちなみに以前からも同様の機能は、SOAPというプロトコルでBing SOAP Serviceとして提供されていました。それらのSOAP APIに加えて、RESTという今風のAPIが追加されました。
Bing Maps REST Servicesは、今のところ公式に日本語情報は提供されていませんが、日本の地理情報を扱うことは可能です。本連載では、特に日本の地理情報の利用を想定してAPIを利用・紹介します。
Location API
今回はBing Maps REST Servicesのうち、Location APIを使ってみましょう。Location APIは、住所や経緯度などの地図情報を取得するAPIです。このAPIは、リクエスト形式によって次の3種類に分類されています。
住所から情報を取得
経緯度から情報を取得
クエリーから情報を取得
住所から経緯度などの地理情報を得る技術はジオコーディング 、逆に経緯度情報から住所などの情報を得るのは逆ジオコーディング と呼びます。このAPIの特徴はどちらも同じLocation APIで扱い、リクエスト形式が異なるもののレスポンス形式は同様の内容になっています。クエリー形式は、住所や東京タワーなどの地名や施設名から情報を得る形式です。
さっそくひとつの例を見てみましょう。次のようなURLにアクセスすると、以下のJSON形式の結果を得ます。
http://dev.virtualearth.net/REST/v1/Locations?countryRegion=JP&adminDistrict=東京都&locality=新宿区&addressLine=西新宿二丁目8番1号&key=BingMapsKey &c=ja-jp
※わかりやすいよう日本語はエンコード前の値を記載しています。
{
"authenticationResultCode" : "ValidCredentials" ,
"brandLogoUri" : "http://dev.virtualearth.net/Branding/logo_powered_by.png" ,
"copyright" : "Copyright © 2010 Microsoft and its suppliers. " ,
"resourceSets" : [
{
"estimatedTotal" : 1 ,
"resources" : [
{
"__type" : "Location:http://schemas.microsoft.com/search/local/ws/rest/v1" ,
"address" : {
"addressLine" : "2丁目8-1" ,
"adminDistrict" : "東京都" ,
"countryRegion" : "日本" ,
"formattedAddress" : "東京都新宿区西新宿2丁目8-1" ,
"locality" : "新宿区" ,
"postalCode" : "160-0023"
},
"bbox" : [
35.686481029111 ,
139.68893000133298 ,
35.691888193111005 ,
139.694337165333
],
"confidence" : "High" ,
"entityType" : "Address" ,
"name" : "東京都新宿区西新宿2丁目8-1" ,
"point" : {
"coordinates" : [
35.689184611111003 ,
139.69163358333299
],
"type" : "Point"
}
}
]
}
],
"statusCode" : 200 ,
"statusDescription" : "OK" ,
"traceId" : "..."
}
URLに指定した値や、レスポンスの内容を見るとある程度使い方が想像できるのではないでしょうか。レスポンス形式はJavaScriptと連携しやすいJSON以外に、各種プログラミング言語でも扱いやすいXML形式が選択できます。また、レスポンス内容もある程度カスタマイズ可能です。
Bing Maps Key
APIを利用するには、Bing Maps Keyをあらかじめ取得しておく必要があります。このKey(文字列)をURLに指定して認証します。Bing Maps KeyはBing Maps Account Center (図1 )で取得します。
図1 Maps Account Center――Bing Maps Keyの作成
Keyの作成は、アプリケーションの名前・URL・種類を入力します。初めて取得する場合は、その前に開発者アカウントを作成する必要があります
Bing Maps Keyは、Bing Maps REST Services以外にBing Maps Silverlight Control SDKなどのでも使います。こちらは、Bing Maps Keyの取得方法も含めて、使ってみよう! Windows Live SDK/API 第30回 で紹介しています。
住所から情報取得
それでは順にリクエスト形式別にAPIの内容をみてみましょう。まず、住所から地理情報の取得です。住所から地理情報を取得する場合、経緯度の取得が主な目的になると思います。レスポンスの内容については既に述べたように、Bing Maps REST ServicesおよびLocation APIで共通の形式になっています。その中にはもちろん経緯度も含まれています。レスポンス内容は最後にまとめて紹介します。
Structured URL
Location APIでは、Structured URL とUnstructured URL と呼ばれる2種類のURL形式が用意されています。Structured URLは、リソースとなる郵便番号や地名を「/」で区切り、URLのディレクトリ部分に指定した形式です。米国の場合、次のように記述します。
http://dev.virtualearth.net/REST/v1/Locations/US/WA/98052/Redmond/1 Microsoft Way?o=xml&key=BingMapsKey
リクエスト結果をみる
上記の場合、州名・郵便番号・街の名前 ・番地が指定されています。そのあとにo パラメーターで出力形式、key パラメーターにBing Maps Keyを指定しています。住所を指定するStructured URLは、日本には対応していませんので、紹介はこのくらいにしておきましょう。次のUnstructured URLを使用すると日本を含む世界の住所から情報を取得可能です。
Unstructured URL
Unstructured URLの形式は次のようになります。
http://dev.virtualearth.net/REST/version /Locations?
countryRegion =countryRegion &
adminDistrict =adminDistrict &
locality =locality &
postalCode =postalCode &
addressLine =addressLine &
key =BingMapsKey
まず、この後の内容すべてにおいて共通の部分について説明します。version はAPIのバージョン「v+バージョン番号」で指定します。現在リリースされているAPIでは「v1」です。そしてBingMapsKey には取得したBing Maps Keyの値を指定します。上記はHTTPですが、HTTPS(https://〜)でアクセスも可能です。
続いて各パラメーターは次のとおりです。
パラメーター
説明
countryRegion
ISOの国名コード を指定します。日本はJPです。
adminDistrict
広域な行政区域を指定します。日本では都道府県名にあたります。ただし必ずしも広域な行政区域とは限りません。
locality
adminDistrict以下の街名などを指定します。日本では主に市区群になります。
postalCode
郵便番号を指定します。
addressLine
番地などを指定します。
adminDistrict・locality・addressLineに関して、日本での分類は、SDKの文書などに明記されているわけではなくAPI利用時の実際のデータから判断した目安です。これらのパラメーターはリクエスト時にすべて指定する必要はなく、ひとつまたは複数を指定すれば問題ありません。また実際に使用してみたところ、Bing Mapsのデータベースで分類されている通りにlocalityやaddressLineを指定しなくとも、結果を得ることができました。
実際の例をみていきましょう。まず住所を番地まで指定した例です。
東京都、新宿区、西新宿二丁目8番1号
http://dev.virtualearth.net/REST/v1/Locations?
countryRegion =JP &
adminDistrict =東京 &
locality =新宿区 &
addressLine =西新宿二丁目8番1号 &
key =BingMapsKey &
c=ja-jp&o=xml
リクエスト結果をみる [1]
上記は日本語をそのまま記載していますが、実際にはエンコードして指定する必要があります。最後に付いているc パラメーターは、サービス地域を表すLocation API共通のculture パラメーターで、日本を指定しています。この指定がない場合、日本語のパラメーターでは結果が得られない場合や、レスポンスの内容が英語であったり、詳細な情報にならない場合があります。この例の場合、「 西新宿2-8-1」の表記でも同じ結果が得られます。
次は、一部のパラメーター名を指定した例です。あいまいな指定の場合、レスポンスに複数の場所の地理情報が含まれている場合があります。
新宿区
http://dev.virtualearth.net/REST/V1/Locations?
locality =新宿区 &
key =BingMapsKey &
c=ja-jp&o=xml
リクエスト結果をみる
日本の郵便番号もcountryRegionとcultureパラメーターを指定すると結果が得られます。ハイフンはあってもなくても同じ結果です。
郵便番号160-0023
http://dev.virtualearth.net/REST/V1/Locations?
countryRegion =JP &
postalCode =160-0023 &
key =BingMapsKey &
c=ja-jp&o=xml
リクエスト結果をみる
adminDistrictパラメーターに村名を指定した場合です。レスポンス内容を確認すると、この村名はadminDistrict・locality・addressLineのどれにも分類されていないようですが、期待した結果を得ることができました。
千早赤阪村
http://dev.virtualearth.net/REST/V1/Locations?
countryRegion =JP &
adminDistrict =千早赤阪村 &
key =BingMapsKey &
c=ja-jp&o=xml
リクエスト結果をみる
最後にローマ字で指定した場合です。cultureパラメーターを指定しない場合の規定値は、英語・米国(en-US)になります。ローマ字の場合は詳細な住所を指定すると結果は該当なしとなるようです。
JP、Tokyo、Sinjuku-ku
http://dev.virtualearth.net/REST/v1/Locations?
countryRegion =JP &
adminDistrict =Tokyo &
locality =sinjuku-ku &
key =BingMapsKey &
o=xml
リクエスト結果をみる
経緯度から情報取得
次は、経緯度から地理情報を取得する方法です。住所から取得と異なりあまりバリエーションがありません。URLの形式は次のようになります。
http://dev.virtualearth.net/REST/v1/Locations/point ?
includeEntityTypes =entityTypes &
key =BingMapsKey
point パラメーターには、緯度・経度を「35.68918461,139.69163358」のようにカンマ区切りで指定します。当然ながら指定は必須です。
includeEntityType パラメーターでは、取得する情報の種類を指定する場合に使用します。たとえば完全な住所や国名だけなど、または施設名などを指定できます。ただし、日本の場合、経緯度からは都道府県程度までしか取得できないようです。使用する場合は、Address , Neighborhood , PopulatedPlace , AdminDivision1 , AdminDivision2 , CountryRegion の値を指定可能です。カンマ区切りで複数指定もできます。その場合、複数の結果が返るのではなく指定した順に優先して結果を得られます。
例をみてみましょう。
http://dev.virtualearth.net/REST/v1/Locations/35.68918461,139.69163358?
key=BingMapsKey &c=ja-jp&o=xml
リクエスト結果をみる
東京都庁のある経緯度ですが、レスポンスの内容をみると、東京都までの情報しか得られていません。EntityTypeはAdminDivision1になっています。
クエリーから情報取得
最後は、クエリーから地理情報を得る方法です。地図検索時に入力するような住所の一部や施設名などのキーワードから情報を取得できます。URL形式は、Structured URLとUnstructured URLの両方が用意されていますが、どちらもほぼ同じです。
Structured URL
http://dev.virtualearth.net/REST/v1/Locations/query ?
key =BingMapsKey
Unstructured URL
http://dev.virtualearth.net/REST/v1/Locations?
query =query &
key =BingMapsKey
query パラメーターに住所や施設名などを指定します。queryは省略してq と指定可能です。
例をみてみましょう。次は住所を指定した場合です。
東京都新宿区西新宿二丁目8番1号
http://dev.virtualearth.net/REST/v1/Locations?
query =東京都新宿区西新宿二丁目8番1号 &
key =BingMapsKey &
c=ja-jp&o=xml
リクエスト結果をみる
次は、東京だけ指定した場合です。この場合、複数の候補地が得られます。
東京
http://dev.virtualearth.net/REST/v1/Locations?
query =東京 &
key =BingMapsKey &
c=ja-jp&o=xml
リクエスト結果をみる
東京タワーを指定した場合です。実は、クエリー形式でなくとも、住所から地理情報を取得するURL形式でも「東京タワー」で同じ結果が得られます。
東京タワー
http://dev.virtualearth.net/REST/v1/Locations?
query =東京タワー &
key =BingMapsKey &
c=ja-jp&o=xml
リクエスト結果をみる
リクエスト方法
以上3種類のリクエスト方法を紹介しましたが、それぞれのURL形式は、Location APIを含めREST Servicesで、次のURL形式をベースとしています。
http://dev.virtualearth.net/REST/version /restApi /resourcePath ?queryParameters &key =BingMapsKey
version パラメーターとkey パラメーターは既に説明しています。APIのバージョンと、Bing Maps Keyでした。restApi パラメーターは、REST APIの種類で、今回の内容ではすべてLocationが指定されていました。resourcePath とqueryParameters パラメーターは、必要に応じて指定される値です。
共通のパラメーター
queryParametersパラメーター部分に指定でき、すべてのリクエストに共通のパラメーターがあります。
既に使用していましたが、ひとつはサービス地域を示す、culture (省略名c )パラメーターです。日本の場合ja-JPと指定します。
もうひとつ使用していたパラメーターが、レスポンスの出力形式を指定する、output (省略名o )パラメーターです。出力形式に関する指定はこれ以外にも次のパラメーターが使用できます。
パラメーター(省略名)
説明
output (o)
JSON・XML形式を選択します。json (規定値)またはxml
suppressStatus (ss)
すべてのレスポンスのHTTPステータスを200 OKで返す。true またはfalse (規定値)
jsonp
JSONP利用時に呼び出す関数名を指定。 例:jsonp=MyCallbackFunction
jsonso
jsonp指定時、呼び出す関数に渡される状態オブジェクト(文字列) 。アプリケーション側でリクエストと対応するレスポンスを結びつけるために主に利用します。
レスポンス内容
レスポンスの内容をみてみましょう。Bing Maps REST Servicesでは、出力形式にJSON・XMLの違いはありますが、次の同じ内容で構成されています。
JSON形式
{
"authenticationResultCode" : "ValidCredentials" ,
"brandLogoUri" : "http://dev.virtualearth.net/Branding/logo_powered_by.png" ,
"copyright" : "Copyright © 2010 Microsoft and its suppliers. " ,
"resourceSets" : [
{
"estimatedTotal" : 1 ,
"resources" : [
]
}
],
"statusCode" : 200 ,
"statusDescription" : "OK" ,
"traceId" : "..."
}
XML形式
<Response xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd = "http://www.w3.org/2001/XMLSchema"
xmlns = "http://schemas.microsoft.com/search/local/ws/rest/v1" >
<Copyright> Copyright © 2010 Microsoft and its suppliers. </Copyright>
<BrandLogoUri> http://dev.virtualearth.net/Branding/logo_powered_by.png </BrandLogoUri>
<StatusCode> 200 </StatusCode>
<StatusDescription> OK </StatusDescription>
<AuthenticationResultCode> ValidCredentials </AuthenticationResultCode>
<TraceId> ... </TraceId>
<ResourceSets>
<ResourceSet>
<EstimatedTotal> 1 </EstimatedTotal>
<Resources>
</Resources>
</ResourceSet>
</ResourceSets>
</Response>
それぞれの要素の内容は次の通りです。JSONとXMLで名前の大文字・小文字が異なりますが適宜読み替えてください。
要素名
説明
StatusCode
HTTPのステータスコード
StatusDescription
HTTPのステータスコードの説明
AuthenticationResultCode
認証結果のコードの説明です。 以下の値のいずれかです。
ValidCredentials
InvalidCredentials
CredentialsExpired
NotAuthorized
NoCredentials
None
TraceId
リクエストごとに一意な値
Copyright
コピーライト情報
BrandLogoUri
Bingロゴ画像のURL。詳しくは利用規約を参照。
ResourceSets
ResourceSetのコレクション
ErrorDetails
エラー内容のコレクション。結果がエラーの場合に含まれています。
ResourceSets はResourceSet のコレクションです。ResourceSetに含まれる内容は次の通りです。
要素名
説明
esitmatedTotal
ResruoceSetに含まれるResrouces内の項目数の概算値
Resources
API固有の情報のコレクション
このResources 要素以下の内容が、Location APIなどREST APIの内容によって異なる構成になっています。Location APIの場合Location 要素がひとつ以上含まれています。Resources以下に含まれている項目(ここではLocation要素)の総数は、概算値となっているので注意してください。これは検索結果のように大量の場合も想定されていると思われます。
Location API固有の内容
Resources要素の中のLocation要素は、Location APIで使用する地理情報です。その内容はリクエスト形式によっては変わりません。
JSON・XML形式は次のようになっています。
JSON形式
{
"__type" : "Location:http://schemas.microsoft.com/search/local/ws/rest/v1" ,
"address" : {
"addressLine" : "2丁目8-1" ,
"adminDistrict" : "東京都" ,
"countryRegion" : "日本" ,
"formattedAddress" : "東京都新宿区西新宿2丁目8-1" ,
"locality" : "新宿区" ,
"postalCode" : "160-0023"
},
"bbox" : [
35.686481029111 ,
139.68893000133298 ,
35.691888193111005 ,
139.694337165333
],
"confidence" : "High" ,
"entityType" : "Address" ,
"name" : "東京都新宿区西新宿2丁目8-1" ,
"point" : {
"coordinates" : [
35.689184611111003 ,
139.69163358333299
],
"type" : "Point"
}
}
XML形式
<Location>
<Name> 東京都新宿区西新宿2丁目8-1 </Name>
<Point>
<Latitude> 35.689184611111 </Latitude>
<Longitude> 139.691633583333 </Longitude>
</Point>
<BoundingBox>
<SouthLatitude> 35.686481029111 </SouthLatitude>
<WestLongitude> 139.68893000133298 </WestLongitude>
<NorthLatitude> 35.691888193111005 </NorthLatitude>
<EastLongitude> 139.694337165333 </EastLongitude>
</BoundingBox>
<EntityType> Address </EntityType>
<Address>
<AddressLine> 2丁目8-1 </AddressLine>
<AdminDistrict> 東京都 </AdminDistrict>
<CountryRegion> 日本 </CountryRegion>
<FormattedAddress> 東京都新宿区西新宿2丁目8-1 </FormattedAddress>
<Locality> 新宿区 </Locality>
<PostalCode> 160-0023 </PostalCode>
</Address>
<Confidence> High </Confidence>
</Location>
Location要素の内容は次の通りです。
要素名
説明
Name
リソース名
Point
経緯度
BoundingBox
エリアを示す2点の経緯度
EntityType
リソースの種類(完全な住所や行政区域、施設名など)
Address
住所 子要素に以下の項目があります。
AddressLine
AdminDistrict
AdminDistrict2
CountryRegion
FormattedAddress
Locality
PostalCode
Confidence
リクエストに対する一致度を以下のいずれかで粟原しています。 High、Medium、Low、Unknown
Address 要素は、リクエストの内容に対して正規化された住所となっていますので、番地を「2-8-1」と指定していても「2丁目8−1」といった値に変化しています。また、各子要素に対する情報がない場合、その子要素は省略されています。住所や地名を利用したい場合、Name 要素やFormattedAddress 要素(含まれている場合)を使用するとよさそうです。
EntityType 要素は、記事では紹介しきれないほどの分類があります(AdminDivision1などだけではなく、AirportやZooなどもあります) 。ただし日本の地理情報がどれだけ分類されているのかは不明です。詳しくは、SDKの文書に記載されています。MSDN Library からCHMまたはPDFファイルがダウンロードできます。
今回はここまでです。次回もBing Maps REST Servicesを紹介の続きです。