Routes API
前回 までにBing Maps REST ServicesのLocation API、Imagery APIを紹介しました。今回は最後のAPI、Routes APIについてです。また、最後にトランザクションレポートについても少しふれています。
Routes APIを利用すると次のふたつのことができます。
出発地から到着地までの経路探索
到着地への主要道路からの経路探索
車または徒歩での経路探索が選択でき、所要時間・距離の取得や、交通情報を利用した探索、交通事故情報や目印となる建物の表示などもサポートしています。
ただし、日本はサポート範囲に一応入っていますが、実質的には日本語で住所を指定できないうえに、探索結果は有用とはいえません。米国のBing Mapsでは、実際に車・徒歩での経路探索がサービスとして提供されていますが(図1 ) 、日本のBing Mapsでは提供されていません[1] 。
図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では経路の描画もサポートしていたため、いくつかのパラメーターは同じ内容です。また、version とBingMapKey についても前回までと同様に、「 v1」とBing Maps Keyを指定します。
パラメーター(省略名)
説明
travelMode
車または徒歩の経路かを指定
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 =point s&
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é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
図3 Usage Report by Category
レポート中のbillableとnon-billableは、エンタープライズ契約している場合に課金対象となるトランザクションかどうかを示しています。企業で大量アクセスが発生するような利用の場合、Microsoftと契約する必要がでてくると思いますが、読者の皆さんの多くは無償で利用できるでしょう。詳しくは、Bing Maps Licensing and Pricing Information や利用規約をご確認ください。
今回は以上です。紹介したBing Maps REST Servicesの各APIは、API単体の利用だけでは特に意味のあるものではありませんので、ぜひ皆さんのアプリケーションに組み入れ、連携し活用してみてください。