使ってみよう! Bing API/SDK

第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]⁠。

図1 Bing Mapsの経路探索サービス
図1 Bing Mapsの経路探索サービス

今のところ日本では実質的に利用できないため、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では経路の描画もサポートしていたため、いくつかのパラメーターは同じ内容です。また、versionBingMapKeyについても前回までと同様に、⁠v1」とBing Maps Keyを指定します。

パラメーター(省略名) 説明
travelMode 車または徒歩の経路かを指定
  • Driving:車(規定)
  • Walking:徒歩
avoid 経路探索時、高速道路や有料道路を使用しない、または最小限に抑えるよう指示するためのオプション
以下の値を指定
  • highways
  • tolls
  • minimizeHighways
  • minimizeTolls
値はカンマ区切りで指定可能
例:avoid=highways,tolls
waypoint.n(wp.n 経路の出発・到着地および中継地を住所・建物名、または経緯度で指定
nの部分は0または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種類のレポートにアクセスできます。

図2 Usage Report
図2 Usage Report
図3 Usage Report by Category
図3 Usage Report by Category

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


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

おすすめ記事

記事・ニュース一覧