第11回　使ってみよう！ Bing Maps REST Services（3）

Routes API

前回までにBing Maps REST ServicesのLocation API、Imagery APIを紹介しました。今回は最後のAPI、Routes APIについてです。また、最後にトランザクションレポートについても少しふれています。

Routes APIを利用すると次のふたつのことができます。

出発地から到着地までの経路探索
到着地への主要道路からの経路探索

車または徒歩での経路探索が選択でき、所要時間・距離の取得や、交通情報を利用した探索、交通事故情報や目印となる建物の表示などもサポートしています。

ただし、日本はサポート範囲に一応入っていますが、実質的には日本語で住所を指定できないうえに、探索結果は有用とはいえません。米国のBing Mapsでは、実際に車・徒歩での経路探索がサービスとして提供されていますが（図1⁠）⁠、日本のBing Mapsでは提供されていません[1]⁠。

今のところ日本では実質的に利用できないため、Routes APIについては、参考までに紹介しておきます。とはいえ図1のように到着地までの道案内を可能にするAPIのため、APIのレスポンスは前回までの内容と比べ複雑なものとなっています。

出発・到着地を指定した経路探索

まず、出発地と到着地を指定して経路を探索する場合です。中継する地点も指定でき、出発・到着地含めて25点まで指定可能です。場所は、住所や建物の名前または経緯度を指定します。

URLの書式

APIのURLの書式は次のようになります。

http://dev.virtualearth.net/REST/version/Routes/travelMode?
  wayPoint.1=wayPoint1&
  waypoint.2=wayPoint2&
  wayPoint.n=wayPointn&
  optimize=optimize&
  avoid=avoidOptions&
  routePathOutput=routePathOutput&
  distanceUnit=distanceUnit&
  key=BingMapsKey

Bing Maps Services共通のURLは次の通りでした。Routes APIの場合、restApi部分にRoutesを指定します。

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

各パラメーターの内容は次の通りです。前回紹介したImagery APIでは経路の描画もサポートしていたため、いくつかのパラメーターは同じ内容です。また、versionとBingMapKeyについても前回までと同様に、「⁠v1」とBing Maps Keyを指定します。

パラメーター（省略名）	説明
travelMode	車または徒歩の経路かを指定 Driving：車（規定） Walking：徒歩
avoid	経路探索時、高速道路や有料道路を使用しない、または最小限に抑えるよう指示するためのオプション以下の値を指定 highways tolls minimizeHighways minimizeTolls 値はカンマ区切りで指定可能例：avoid=highways,tolls
waypoint.n（wp.n）	経路の出発・到着地および中継地を住所・建物名、または経緯度で指定 nの部分は０または1から1ずつインクリメントとした値を順番に指定、2点以上を指定ルート指定形式の場合必須例：wp.1=Eiffel%20Tower&wp.2=louvre%20museum
optimize（optmz）	以下の値を指定 distance：最短距離経路優先 time：最短時間経路優先（規定値） timeWithTraffic：交通情報を考慮した最短時間経路優先
routePathOutput（rpo）	レスポンスに経路を表す経緯度のコレクションを含めるかを指定 points：含める None：含めない（規定値）
distanceUnit（du）	使用する距離の単位 Mile または mi Kilometaer または km（規定値）

上記のうちwaypoint.nのみ必須のパラメーターです。travelModeを省略する場合は次のように /Routes の後にすぐクエリーを付けてURLを表記します。

http://dev.virtualearth.net/REST/version/Routes?
wayPoint.1=wayPoint1&...

経路探索の例

実際に経路探索をしてみましょう。以下は、建物の名前を出発・到着地点に指定した場合の徒歩による経路探索です。

http://dev.virtualearth.net/REST/v1/Routes/Walking?
  wp.1=Eiffel%20Tower&
  wp.2=louvre%20museum&
  optmz=distance&
  key=BingMapsKey&o=xml

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

次の例は経緯度を指定した場合です。また経路の経緯度情報も取得しています。レスポンスをみると複数の経緯度情報が含まれているのがわかります。

http://dev.virtualearth.net/REST/v1/Routes?
  wp.1=40,-120&
  wp.2=40.5,-120.5&
  rpo=points&
  key=BingMapsKey&o=xml

リクエスト結果をみる

主要道路からの経路探索

Routes APIのもうひとつの機能は到着地点を指定し、そこまでの東西南北の主要な道路からの経路探索です。日本はサポートされていません。

URLの書式

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

http://dev.virtualearth.net/REST/version/Routes/FromMajorRoads?
  destination=destination&
  exclude=routes&
  rpo=routePathOutput&
  du=distanceUnit&
  key=BingMapsKey

各パラメーターは次の通りです。出発・到着地から経路探索と同じパラメーターは省略しています。

パラメーター（省略名）	説明
destination（dest）	到着地となる場所を住所・建物名、または経緯度で指定例：dest=1 Microsoft Way Redmond WA
exclude（excl）	「routes」のみ指定でき、指定した場合、出発地のみの情報となる（経路情報を含まない）

経路探索の例

実際の例は次のようになります。

http://dev.virtualearth.net/REST/v1/Routes/FromMajorRoads?
  destination=1%20Microsoft%20Way%20Redmond%20WA&
  excl=routes&
  key=BingMapsKey&o=xml

リクエスト結果をみる

結果をみると、到着地に対して東西南北の道路が出発地となっています。

レスポンス内容

レスポンス内容の構造はBing Maps REST Servicesで共通になっています。共通の構造は第9回を参照してください。ここでは、Routes APIで使用されるレスポンスデータのみ簡単に紹介します。Routes APIで得られる<Resources>要素以下のXML形式の内容は次のようになっています。

<Route>
  <Id>v60,i0,a0,cen-US,dAAAAAAAAAAA=,y0,s1,m2,o2,t0,w8MtXBGc2NAA=~pl3oNtmFMgoAAA4B/f9/PwA=~RWlmZmVsIFRvd2VyLCBQYXJpcywgRnJhbmNl~~~,wqt5XBKwjNQA=~pl3oNglfMgoAAA4BzhFBPwE=~TG91dnJlLCBQYXJpcywgRnJhbmNl~~~,k1 </Id>
  <BoundingBox>
    <SouthLatitude>48.857842683792114 </SouthLatitude>
    <WestLongitude>2.292097806930542 </WestLongitude>
    <NorthLatitude>48.862928152084351 </NorthLatitude>
    <EastLongitude>2.335287407040596 </EastLongitude>
  </BoundingBox>
  <DistanceUnit>Kilometer </DistanceUnit>
  <DurationUnit>Second </DurationUnit>
  <TravelDistance>3.884 </TravelDistance>
  <TravelDuration>2797 </TravelDuration>
  <RouteLeg>
  .. 省略 ..
  </RouteLeg>
  <RoutePath>
  .. 省略 ..
  </RoutePath>
</Route>

まずは<Route>要素直下の内容です。各要素の内容は以下の通りです。JSON形式で取得した場合は、大文字小文字などが異なりますが、適宜読み替えてください。

要素名	説明
Id	リソースごとに一意の値
BoundingBox	経路を表示するのに最適なエリア
DistanceUnit	距離の単位
DurationUnit	時間の単位
TravelDistance	経路の距離
TravelDuration	経路の所要時間
RouteLeg	出発地・到着地の経路情報 RouteLeg要素は複数含まれている場合がある
RoutePath	経路を表す経緯度のコレクション routePathOutputパラメーターを指定した場合に含まれている

続いて<RouteLeg>要素の内容は次のようになっています。

<RouteLeg>
<TravelDistance>3.884 </TravelDistance>
<TravelDuration>2797 </TravelDuration>
<ActualStart>.. 省略 ..</ActualStart>
<ActualEnd>.. 省略 ..</ActualEnd>
<StartLocation>.. 省略 ..</StartLocation>
<EndLocation>.. 省略 ..</EndLocation>
<ItineraryItem>.. 省略 ..</ItineraryItem>
<ItineraryItem>.. 省略 ..</ItineraryItem>
<ItineraryItem>.. 省略 ..</ItineraryItem>
</RouteLeg>

要素名	説明
TravelDistance	経路の距離
TravelDuration	経路の所要時間
ActualStart	出発地点の経緯度経緯度を指定した経路探索の場合、指定地点から近い道路の位置に置き換わる
ActualEnd	到着地点の経緯度
StartLocation	出発地点の情報住所や建物名を指定して経路探索した場合に情報が含まれ、複数ある場合がある
EndLocation	終了地点の情報（複数）
ItineraryItem	到着地までの指示（複数）

上記の<StatLocation>と<EndLocation>要素の内容は次のようになります。以下はStartLocationの場合です。EndLocationの場合も要素名が異なるだけで、含まれる子要素は変わりありません。

<StartLocation>
  <Name>Eiffel Tower, Paris, France </Name>
  <Point>
    <Latitude>48.858250379562378 </Latitude>
    <Longitude>2.2944950312376022 </Longitude>
  </Point>
  <BoundingBox>
    <SouthLatitude>48.853590041399 </SouthLatitude>
    <WestLongitude>2.2851307690143585 </WestLongitude>
    <NorthLatitude>48.8629100471735 </NorthLatitude>
    <EastLongitude>2.3038592934608459 </EastLongitude>
  </BoundingBox>
  <EntityType>Monument </EntityType>
  <Address>
    <AdminDistrict>IdF </AdminDistrict>
    <AdminDistrict2>Paris </AdminDistrict2>
    <CountryRegion>France </CountryRegion>
    <FormattedAddress>Eiffel Tower, Paris, France </FormattedAddress>
    <Locality>Paris </Locality>
  </Address>
  <Confidence>High </Confidence>
</StartLocation>

要素名	説明
Name	地名、建物の名前など
Point	経緯度
BoundingBox	エリアを示す2点の経緯度
EntityType	場所の種類（Monumentなど）
Address	住所
Confidence	一致度（High、Medium、Low、Unknownのいずれか）

到着地までの指示が記載されている<InitineraryItem>要素の内容は次のようになります。

<ItineraryItem>
  <TravelMode>Walking </TravelMode>
  <TravelDistance>0 </TravelDistance>
  <TravelDuration>0 </TravelDuration>
  <ManeuverPoint>
    <Latitude>48.861699029803276 </Latitude>
    <Longitude>2.335287407040596 </Longitude>
  </ManeuverPoint>
  <Instruction maneuverType="ArriveFinish">Arrive at Louvre, Paris, France on the right </Instruction>
  <CompassDirection>east </CompassDirection>
  <Hint hintType="PreviousIntersection">The last intersection is Place du Carrousel </Hint>
  <Hint hintType="NextIntersection">If you reach Cour Napol&eacute;on, you've gone too far </Hint>
</ItineraryItem>

要素名	説明
CompassDirection	向いている方角（eastなど）
Instruction	指示（TurnLeftなど）
TravelMode	指定したTravelModeの値
TravelDistance	対象のItineraryItemでの所要距離
TravelDuration	対象のItineraryItemでの所要時間
ManeuverPoint	指示に沿った行動をとる地点となる経緯度
Hint	指示に沿った行動をとるために手助けとなる追加情報直前・直後の交差点情報、目印となる建物
Warning	対象経路の詳細情報交通事故情報など

レスポンス内容は以上です。リクエスト時にcultureパラメーターにより日本を指定した場合、Instructionは日本語で返ってきます。

Bing Mapsトランザクションレポート

さて、Bing Maps REST Servicesの各APIを3回にわたり紹介してきましたが、今回で一旦終了です。ここで最後に、Bing Mapsのトランザクションレポートについて紹介しておきましょう。

Bing Maps REST Servicesに限らず、Bing Maps Keyを利用するいくつかのサービスではその呼び出し回数などをレポート形式で見ることができます。また、各種フォーマットで出力も可能です。

レポートは、Bing Maps Keyの取得時に利用した、Bing Maps Account Centerで確認できます。左側のメニューの、View my Bing Maps API usageをクリックすると、Usage Report（図2）とUsage Report by Category（図3）の2種類のレポートにアクセスできます。

レポート中のbillableとnon-billableは、エンタープライズ契約している場合に課金対象となるトランザクションかどうかを示しています。企業で大量アクセスが発生するような利用の場合、Microsoftと契約する必要がでてくると思いますが、読者の皆さんの多くは無償で利用できるでしょう。詳しくは、Bing Maps Licensing and Pricing Informationや利用規約をご確認ください。

今回は以上です。紹介したBing Maps REST Servicesの各APIは、API単体の利用だけでは特に意味のあるものではありませんので、ぜひ皆さんのアプリケーションに組み入れ、連携し活用してみてください。