Imagery API

前回はBing Maps REST ServicesのLocation APIを紹介しました。今回は同じくREST ServicesのひとつImagery APIについてです。Imagery APIを利用すると、大きく分けて次のふたつのことができます。

• 地図画像の取得
• メタデータの取得

ひとつ目の地図画像の取得では、指定した地域の画像をJPEGやPNG形式で取得でき、Blogなどに貼り付けて使えます。また、プッシュピンの描画などもできます。ふたつ目のメタデータの取得とは、Bing Mapsを構成するタイル状の画像の情報の取得です。

Imagery APIは日本・日本語に対応していませんが、日本のサービス向けにも利用できると思われる部分を中心に紹介します。

画像の取得

場所の指定

それでは画像の取得方法からみていきましょう。地図の一部分を画像として切り出すわけですが、取得する場所の指定は次の方法が用意されています。

• 画像の中心となる経緯度とズームレベルの指定
• 2点の経緯度で表示エリアの指定
• ルートの指定
• クエリーの指定

上記の最初のふたつは、経緯度を指定するものです。

ルートの指定では、複数の地点を経緯度や住所で指定すると車または徒歩での経路情報を表示するのに最適な範囲の地図が得られます。ただし日本の場合、結果は得られますがルート情報としてはあまり有用とはいえません。また日本語での場所指定もできません。

クエリーの指定では、住所や建物名などを指定し、その地域を表すのに最適な範囲の地図が得られます。ただしこちらも日本語がサポートされていませんので日本語や詳細な住所では結果を得られません。

以上より、今のところ日本での利用は経緯度指定によるものが使えそうです。地図画像は日本語表記のものが得られます。また、クエリーの指定について、Imagery APIは日本語対応していませんが、前回のLocation APIは対応していますので、Location APIから得られた経緯度をImagery APIで利用する組み合わせが可能です。

場所の指定方法にもよりますが、地図画像に対して主に次の操作ができます。

• プッシュピンの描画
• ルートの描画
• 大きさの指定

リクエストURLの書式

以上をふまえて、画像を取得するためのURLの書式とそのパラメーターをみていきましょう。

画像を取得するURL書式は以下のようになります（青字が値を指定する箇所です⁠）⁠。

• http://dev.virtualearth.net/REST/version/Imagery/Map/imagerySet/centerPoint/zoomLevel/Routes/travelMode?
    mapArea=mapArea&
    waypoint.1=routeWaypoint1&
    waypoint.2=routeWaypoint2&
    waypoint.n=routeWaypointn&
    avoid=avoidOptions&
    mapSize=mapSize&
    pushpin=pushpin&
    mapLayer=mapLayer&
    key=BingMapsKey

パラメーターが多いですがすべて使用するわけではなく、場所の指定方法に合わせて選択または組み合わせて使います。たとえば、ルートを指定して画像の中心場所を指定するなどが可能です。

クエリーを指定する場合は次の書式になります。

• http://dev.virtualearth.net/REST/version/Imagery/Map/imagerySet/query?
    mapSize=mapSize&
    mapLayer=mapLayer&
    key=BingMapsKey

前回も述べたようにBing Maps REST Servicesは下記の共通のURLの書式に従っています（HTTPSもサポートしています⁠）⁠。Imagery APIの場合、restApi部分がImageryになっています。

• http://dev.virtualearth.net/REST/version/restApi/resourcePath?queryParameters&key=BingMapsKey

Imagery APIの各パラメーターは次の通りです。versionとBingMapsKeyについては前回説明しています。「⁠v1」とBing Maps Keyを指定します。

場所を特定できる、centerPointとzoomLevel, mapArea, waypoint.nのいずれかは必須のパラメーターです。当然ながらクエリー形式指定の場合、queryパラメーターは必須です。

少し重要度の低いルート指定関連のパラメーターを次にまとめています。いずれのパラメーターも省略可です。

URL書式をみるとcenterPointとzoomLevelは、URLのパス部分にあります。ルートについても各地点の指定はクエリー部分（⁠「⁠?」以降）にありますが、ルート指定時はパスにRoutesを指定します。クエリー指定時も場所を示すクエリーはパス部分に記述します。エリアのみクエリー部分で表現されていることがわかります。

中心の経緯度とズームレベルだけを指定する場合は、「⁠/Routes/travelMode」を省略し次のようにパスを構成します。

• /REST/version/Imagery/Map/imagerySet/centerPoint/zoomLevel

ルートのみ指定する場合は、/centerPoint/zoomLevel部分を省略し次のようにパスを構成します。

• /REST/version/Imagery/Map/imagerySet/Routes/travelMode

さらにtravelModeを省略すると次のようになります。

• /REST/version/Imagery/Map/imagerySet/Routes

いずれも指定する順番は変更せずに必要ない部分を省略します。URLの「?」以降のクエリー部分は順不同です。次の実際の例を見て確認してみましょう。

画像取得の例

実際に取得した画像をみてみましょう。中心となる経緯度とズームレベルの指定した場合は図1のようになります。

• http://dev.virtualearth.net/REST/v1/Imagery/Map/AerialWithLabels/35.689184611,139.691633583/17?
    key=BingMapsKey

エリアを示す2点の経緯度を指定した場合は図2のようになります。

• http://dev.virtualearth.net/REST/v1/Imagery/Map/AerialWithLabels?
    mapArea=35.686481029111,139.68893000133298,35.691888193111005,139.694337165333&
    key=BingMapsKey

ルートの指定は図3のようになります。各地点にはフラッグ形式のプッシュピンが描画されます。

• http://dev.virtualearth.net/REST/v1/Imagery/Map/Road/Routes/Driving?
    waypoint.1=Tokyo&
    waypoint.2=Kyoto&
    key=BingMapsKey

クエリーの指定は次のようになります。クエリーが示す地点には図4のようなプッシュピンが描画されます。

• http://dev.virtualearth.net/REST/v1/Imagery/Map/Road/Tokyo?
    key=BingMapsKey

次はプッシュピンを描画した場合です。経緯度とズームレベルを指定した地図の3か所にプッシュピンを描画しています。図5のように一応、プッシュピンに日本語の表示も可能です。

• http://dev.virtualearth.net/REST/v1/Imagery/Map/Road/35.689184611,139.691633583/8?&
    pp=35.68955124,139.6918197;34;%E6%9D%B1&
    pp=35.856954163889,139.648881555556;36;%E5%9F%BC&
    pp=35.605059852778,140.123322944444;36;%E5%8D%83&
    key=BingMapsKey

プッシュピンの種類や表示する文字列は「pp=35,139」や「pp=35,139;;A」のように省略可能です。指定できる種類の番号は0から36まで用意されています。詳しくはMSDN Libraryからダウンロードできる文書を参照してください。

次はルートを描画した場合です。

• http://dev.virtualearth.net/REST/v1/Imagery/Map/Aerial/Routes?
    mapArea=35.5,139,35.9,139.8&
    wp.0=35.68955124,139.6918197&
    wp.1=35.020907305556,135.755329916667&
    key=BingMapsKey

いずれの場所の指定方法でも、次のように画像の大きさを指定できます。

• http://dev.virtualearth.net/REST/V1/Imagery/Map/Road?
    mapArea=37.317227,-122.318439,37.939081,-122.194565&
    ml=TrafficFlow&
    ms=200,200&
    key=BingMapsKey

上図は交通情報も表示しています。交通情報なしの場合は下図のようになります。

メタデータの取得

次はメタデータの取得です。Bing Mapsの地図は256x256ピクセルの画像をタイル状に並べて構成されています。Imagery APIを利用すると、そのタイル構成などの情報が得られます。指定した経緯度とズームレベルの地点を含むタイル画像のURLが取得可能で、主にこのために利用すると考えてよいでしょう。

URLの書式

メタデータ取得のURL書式には次の通りです。

• http://dev.virtualearth.net/REST/version/Imagery/Metadata/imagerySet/centerPoint?
    orientation=orientation&
    zoomLevel=zoomLevel&
    include=ImageryProviders&
    key=BingMapsKey

そして、各パラメーターは次の通りです。

メタデータの取得では、Bird's eyeと呼ばれる概観図の情報も取得可能です。その場合、imagerySetパラメーターには、BirdseyeまたはBirdseyeWithLabelsを指定します。

経緯度とズームレベルは省略可能で、その場合は指定した地図の種類に関する情報が得られます。ただし、概観図は必ず経緯度・ズームレベルの指定が必要です。そのため、経緯度・ズームレベルを指定しないパターンは、imagerySetパラメーターにAerial、AerialWithLabels、Roadのいずれかを指定した3パターンのみです。

メタデータの取得例

実際にメタデータを取得してみましょう。特定の場所を指定しない場合は次のようになります。この例はAerial（航空写真）を指定した場合です。

航空写真のメタデータ

• http://dev.virtualearth.net/REST/v1/Imagery/Metadata/Aerial?
    key=BingMapsKey&o=xml

リクエスト結果をみる[1]

次は経緯度を指定した場合です。

指定した経緯度が含まれるタイル画像情報

• http://dev.virtualearth.net/REST/v1/Imagery/Metadata/Aerial/35.689184611,139.691633583?
    zoomLevel=19&
    key=BingMapsKey&o=xml

リクエスト結果をみる

次は地図の種類に概観図を指定した場合です。

概観図のタイル画像情報

• http://dev.virtualearth.net/REST/v1/Imagery/Metadata/Birdseye/35.689184611,139.691633583?
    orientation=90&
    zoomLevel=19&
    key=BingMapsKey&o=xml

リクエスト結果をみる

リクエスト結果の各値については、次のレスポンス内容で説明します。

レスポンス内容

画像取得のレスポンス

画像の取得の場合、レスポンスはJPEG・PNG・GIF形式のいずれかの画像となります。これらの形式の選択はできません。Bing Maps Keyやパラメーターの誤りはHTTPのステータスコードで判断するしかありません（具体的なパラメーターの誤りはわかりません⁠）⁠。

メタデータ取得のレスポンス

メタデータ取得の場合、XMLまたはJSON形式でレスポンスが返ってきます。レスポンス内容の構造はBing Maps REST Servicesで共通になっています。共通の構造は前回の内容を参照してください。ここではメタデータ特有の部分の内容を説明します（<Resources＞要素以下の内容⁠）⁠。

メタデータの取得で得られるJSON・XML形式の内容は次のような内容になっています。

航空写真のメタデータ

{
    "__type": "ImageryMetadata:http://schemas.microsoft.com/search/local/ws/rest/v1", 
    "imageHeight": 256, 
    "imageUrl": "http://{subdomain}.tiles.virtualearth.net/tiles/a{quadkey}.jpeg?g=580&mkt={culture}&token={token}", 
    "imageUrlSubdomains": [
        "t0", 
        "t1", 
        "t2", 
        "t3"
    ], 
    "imageWidth": 256, 
    "imageryProviders": null, 
    "vintageEnd": null, 
    "vintageStart": null, 
    "zoomMax": 19, 
    "zoomMin": 1
}

<ImageryMetadata>
        <ImageUrl>http://{subdomain}.tiles.virtualearth.net/tiles/a{quadkey}.jpeg?g=580&mkt={culture}&token={token}</ImageUrl>
        <ImageUrlSubdomains>
                <string>t0</string>
                <string>t1</string>
                <string>t2</string>
                <string>t3</string>
        </ImageUrlSubdomains>
        <ImageWidth>256</ImageWidth>
        <ImageHeight>256</ImageHeight>
        <ZoomMin>1</ZoomMin>
        <ZoomMax>19</ZoomMax>
</ImageryMetadata>

指定した経緯度が含まれるタイル画像情報

{
    "__type": "ImageryMetadata:http://schemas.microsoft.com/search/local/ws/rest/v1", 
    "imageHeight": 256, 
    "imageUrl": "http://t0.tiles.virtualearth.net/tiles/a1330021123012310220.jpeg?g=580&mkt={culture}&token={token}", 
    "imageUrlSubdomains": null, 
    "imageWidth": 256, 
    "imageryProviders": null, 
    "vintageEnd": "05 Apr 2007 GMT", 
    "vintageStart": "05 Apr 2007 GMT", 
    "zoomMax": 19, 
    "zoomMin": 19
}

<ImageryMetadata>
        <ImageUrl>http://t0.tiles.virtualearth.net/tiles/a1330021123012310220.jpeg?g=580&mkt={culture}&token={token}</ImageUrl>
        <ImageWidth>256</ImageWidth>
        <ImageHeight>256</ImageHeight>
        <ZoomMin>19</ZoomMin>
        <ZoomMax>19</ZoomMax>
        <VintageStart>2007-04-05</VintageStart>
        <VintageEnd>2007-04-05</VintageEnd>
</ImageryMetadata>

各要素の内容は以下の通りです。XMLとJSON形式では大文字小文字などが異なりますが、適宜読み替えてください。

次の要素は概観図にのみ含まれる内容です。

次に、メタデータのこれらの値を使用してタイル画像のURLを求めてみましょう。

タイル画像

タイル画像を得るには、メタデータのImageUrl要素の値を使用します。URLの{quadkey}や{culture}部分に適切な値を指定することでタイル画像のURLを作成します。

航空写真のメタデータのImageUrl要素の値は次のようになっています。

• http://{subdomain}.tiles.virtualearth.net/tiles/a{quadkey}.jpeg?g=580&mkt={culture}&token={token}

経緯度を指定した場合に得られるURLにも{culture}などの文字列が含まれています。URL内に登場するこれらの値は次の通りです。

{subdomain}

{subdomain}は、負荷分散のため使用されているサブドメイン名です。t0やt1などImageUrlSubdomains要素の値のいずれかを指定します。

{quadkey}

{quadkey}は、QuadKeysと呼ばれるタイルの番号です。指定した経緯度が含まれるタイル画像情報を取得した場合、この{quadkey}部分には「1330021123012310220」のように値が格納されています。

QuadKeysは、タイルの地図上の位置とズームレベルによって決まります。Bing Mapsの場合、ズームレベルが1のとき図9のように2x2のタイルで構成されています。ズームレベルが1あがると1枚のタイルで表現されていた領域が2x2の4枚で表現されるようになります。

QuadKeysを求めるには、まずタイルの位置をXとYの座標で表します。図10のように横軸をX、縦軸をYとし、左上の座標を（0,0）とします。

上図の場合はズームレベルが3の場合です。座標（3,5）のQuadKyesは次のように求めます。

1. X=3, Y=5 をズームレベルと同じ桁数の2進数で表現
   • X = 011
   • Y = 101
2. 求めた2進数の値を合わせて4進数で表現
   (011101)₂ = (213)₄

求めた4進数の値、213がQuadKeysです。図9の値と一致していますね。このように求めたQuadKeysは、1段階前のズームレベルでの値に0～3が付いて表現される特徴があります。

ちなみに、QuadKeysを含む画像ファイル名は、「⁠a1330021123012310220.jpeg」のようになり、先頭のアルファベットは、r, a, hのいずれかになり、道路地図・航空写真・航空写真＋道路地図で異なっています。

{culture}

{culture}には、サービス地域を指定します。日本の場合はja-JP、米国の場合はen-USです。

{token}

{token}は、API利用者には必要のない値です。値を指定する必要はありません。

{tileId}

{tileId}は、概観図で使用するタイル番号です。概観図の場合、QuadKeysの規則に従って番号が付いていません。メタデータ取得時に指定した経緯度の概観図のタイルは、図11のようにTilesXとTilesY要素の値のタイル数で構成されています。左上から行と列に順に0から付けられている値がタイル番号です。

以上が、タイルのURL書式の内容と、タイルの構成についてでした。この内容から特定の地点のタイル画像の取得が可能になったかと思います。

おわりに

今回はここまでです。いかがでしたでしょうか。特にメタデータの取得は、使い方によってはおもしろい利用方法があるかもしれません。今回のImagery APIが利用されていたわけではありませんが、タイル画像を利用して、Silverlight版のBing Mapsがリリースされる以前から、SilverlightのDeep Zoom機能を利用して地図コントロールを作成しているオープンソースプロジェクトもありました（DeepEarth⁠）⁠。また、Google Mapsのタイル構成と似ているため、Google MapsとBing Mapsを組み合わせたサービスやアプリケーションも可能かもしれません。おもしろいアイデアが思い付いた方は、ぜひサービス作成にトライしてみてください。

次回もBing Maps REST Servicesを紹介予定です。