1. Spatial開発者ガイド
  2. 空間Webサービス
  3. ルーティング・エンジン
  4. WSServlet XML APIを使用した場所ベースの問合せ

14.4 WSServlet XML APIを使用した場所ベースの問合せ

WSServletは、制限速度および走行速度に関連する軽量な場所ベースの問合せを実行するためのルーティング・エンジン・サーブレットです。

HTTPプロトコルを使用して、XML形式でリクエストを送信します。HTTPリクエスト(GETまたはPOSTメソッド)を使用する場合、そのリクエストには、xml_requestというパラメータがあり、その値は、リクエストのXML文書が含まれる文字列であると想定されます。

サーブレットへのリクエストの書式は、次のとおりです。

http://hostname:port/routeserver/ws/WSServlet?xml_request=xml-request

この書式の詳細は次のとおりです。

  • hostname: ルーティング・エンジンが実行されているサーバーのネットワーク・パスです。

  • port: アプリケーション・サーバーがリスニングするポートです。

  • routeserver/ws/WSServlet: サーブレットのディレクトリです。

  • xml-request: URLエンコードされたXMLリクエストです。HTMLのGETまたはPOSTメソッドを使用して送信されます。

入力XMLは、すべてのリクエストに必須です。出力は、XML文書になります。

WSServletでは次の異なるリクエストを処理します。

  • 制限速度: 場所の最も近いエッジの制限速度を戻します。

  • 走行速度: 場所の最も近いエッジの平均走行速度を戻します。

関連トピックのリクエストおよびレスポンスは、読みやすくするために必要に応じて書式設定されます。

親トピック: ルーティング・エンジン

14.4.1 1つ以上の場所の指定

WSServletサーブレットへのリクエストでは、単一または複数の場所を指定できます。単一の場所を指定するリクエストには、<location>要素が1つあります。複数の場所を指定するリクエストには、<location>要素が複数あり、batchリクエストと呼ばれます。

WSServletサーブレットへのリクエストは、locationTypeタイプ(単一または複数の場所を指定するために使用されるXMLスキーマ定義タイプ)およびその他の関連属性を参照します。このタイプは次のように定義します。 

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
	<xsd:complexType name="locationType">
		<xsd:attribute name="id" type="xsd:string" use="required"/>
		<xsd:attribute name="longitude" type="xsd:string" use="required"/>
		<xsd:attribute name="latitude" type="xsd:string" use ="required"/> 
		<xsd:attribute name="requestTime" type="xsd:string"/>
		<xsd:attribute name="timeFormat" type="xsd:string" default="dd MMM yyyy HH:mm"/>
	</xsd:complexType>
</xsd:schema>

このタイプの内容は次のとおりです。

  • id: 場所のID (識別子)値が含まれる文字列(必須属性)。

  • longitude: 場所の経度が含まれる文字列(必須属性)。

  • latitude: 場所の緯度が含まれる文字列(必須属性)。

  • requestTime: リクエスト時間が含まれる文字列。デフォルトの時間書式(dd MMM yyyy HH:mm)またはカスタマイズされた書式に従う必要があります。

  • timeFormat: リクエスト時間書式が含まれる文字列。デフォルト値は"dd MMM yyyy HH:mm"ですが、"yyyy/mm/dd HH:mm"や"mm-dd-yyyy HH:mm"といった時間書式にカスタマイズできます。

親トピック: WSServlet XML APIを使用した場所ベースの問合せ

14.4.2 WSServletでの制限速度のサポート

このトピックでは、制限速度に関連するリクエストおよびレスポンスの例と、リクエストおよびレスポンスのスキーマ定義を示します。リクエストとそれに対応するレスポンスは、単一または複数の場所に対して作成できます。

親トピック: WSServlet XML APIを使用した場所ベースの問合せ

14.4.2.1 制限速度リクエストおよび制限速度レスポンスの例

例14-21 制限速度リクエスト(単一の場所)

この例は、場所ID (location id="1291")と経度/緯度ペアを使用して単一の場所を指定している制限速度リクエストを示しています。 

<speedLimitRequest requestId="0001">
	<location id="1291" longitude="-93.2857" latitude="45.1705"/>
</speedLimitRequest>

このリクエストからのレスポンスは次のようになります。 

<speedLimitResponse requestId="0001" unit="mph">
	<edgeResponse locationId="1291" edgeId="-20190321" speedLimit="24.9"/>
</speedLimitResponse>

リクエストで速度単位を指定しなかったため、サーブレットではデフォルト単位のマイル/時間(mph)が使用されます。この場合、制限速度は実際には40km/時間(kmph)としてポストされますが、サーブレットではレスポンスでmph (24.9)に変換されます。レスポンスでkm/時間を示すようにするには、リクエストにunit="kmph"を含める必要があります。

例14-22 制限速度リクエスト(複数の場所)

この例は、それぞれが独自の場所IDを持ち、経度/緯度ペアによって指定されている3つの場所での制限速度に関するバッチ・リクエストです。リクエストには単位のkm/時間(kmph)を指定します。

<speedLimitRequest requestId="0002" unit="kmph">
	<location id="1291" longitude="-93.2857" latitude="45.1705"/>
	<location id="211" longitude="-93.24049" latitude="46.69592"/>
	<location id="376" longitude="-71.46006" latitude="42.71004"/>
</speedLimitRequest>

このリクエストからのレスポンスは次のようになります。 

<speedLimitResponse requestId="0002" unit="kmph">
	<edgeResponse locationId="1291" edgeId="-20190321" speedLimit="40.0"/>
	<edgeResponse locationId="211" edgeId="125949436" speedLimit="95.0"/>
	<edgeResponse locationId="376" edgeId="22325991" speedLimit="20.0"/>
</speedLimitResponse>

レスポンスには、リクエストされた各場所の<edgeResponse>要素が含まれています。つまり、場所ごとに、その場所に関連付けられている点(経度/緯度)での道路または通りについて制限速度を戻します。

親トピック: WSServletでの制限速度のサポート

14.4.2.2 制限速度リクエストおよび制限速度レスポンスのスキーマ定義

制限速度リクエストのXMLスキーマ定義(XSD)は次のとおりです。 

<?xml version="1.0"  ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="speedLimitRequest">
		<xs:complexType>
			<xs:sequence>
				<xs:element maxOccurs="unbounded" name="location" type="locationType"/>
			</xs:sequence>
			<xs:attribute name="requestId" type="xs:string" use="required"/>
			<xs:attribute name="requestType" type="xs:string" fixed="speedLimit"/>
			<xs:attribute name="unit" default="mph">
				<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value="mph"/>
						<xs:enumeration value="kmph"/>
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
		</xs:complexType>
	</xs:element>
</xs:schema>

この定義での<speedLimitRequest>の内容は次のとおりです。

  • requestId: リクエストのIDが含まれる文字列(必須属性)。

  • requestType: 固定値"speedLimit"が含まれる文字列(オプション属性)。この属性は、リクエストに指定する必要はなく、JSON解析で後で使用できるようにするためのものです。

  • unit: 速度単位が含まれる文字列(オプション属性)。"mph" (マイル/時間)および"kmph" (km/時間)のみがサポートされます。

  • location要素: 単一の場所または場所のリストを指定できます(「1つ以上の場所の指定」を参照)。

制限速度レスポンスのXMLスキーマ定義(XSD)は次のとおりです。 

<?xml version="1.0"  ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="speedLimitResponse">
		<xs:complexType>
			<xs:sequence>
				<xs:element maxOccurs="unbounded" name="edgeResponse">
					<xs:complexType>
						<xs:attribute name="locationId" type="xs:string"/>
						<xs:attribute name="edgeId" type="xs:long"/>
						<xs:attribute name="speedLimit" type="xs:double"/>
						<xs:attribute name="error" type="xs:string"/>
					</xs:complexType>
				</xs:element>
			</xs:sequence>
			<xs:attribute name="requestId" use="required"/>
			<xs:attribute name="unit" default="mph">
				<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value="mph"/>
						<xs:enumeration value="kmph"/>
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
		</xs:complexType>
	</xs:element>
</xs:schema>

この定義での<speedLimitResponse>の内容は次のとおりです。

  • requestId: リクエストのIDが含まれる文字列(必須属性)。

  • unit: 速度単位が含まれる文字列(オプション属性)。サポートされているのは、mph (マイル/時間)およびkmph (km/時間)のみです。デフォルトはmphです。

  • edgeResponse: 1つ以上の要素。単一のエッジまたはエッジのリストのいずれかです。次の属性があります。

    • locationId: 場所のIDが含まれる文字列。

    • edgeId: 入力場所の最も近いエッジのIDが含まれる文字列。

    • speedLimit: 制限速度。

  • error: リクエストが正しくない場合に、エラー・メッセージが含まれる文字列。

親トピック: WSServletでの制限速度のサポート

14.4.3 WSServletでの走行速度のサポート

このトピックでは、走行速度に関連するリクエストおよびレスポンスの例と、リクエストおよびレスポンスのスキーマ定義を示します。リクエストとそれに対応するレスポンスは、単一または複数の場所に対して作成できます。

走行速度のAPIは、制限速度のAPIと似ていますが、主な相違点は入力で時間(requestTime属性)が必須であることです。

親トピック: WSServlet XML APIを使用した場所ベースの問合せ

14.4.3.1 走行速度リクエストおよび走行速度レスポンスの例

例14-23 走行速度リクエスト(単一の場所)

この例は、場所ID (location id="1291")、経度/緯度ペア、平均走行速度を求める時間(requestTime="08 Feb 2017 15:00")を使用して単一の場所を指定している走行速度リクエストを示しています。指定された時間ではデフォルト書式の"dd MMM yyyy HH:mm"が使用されるため、リクエストで書式を指定する必要はありません。 

<trafficSpeedRequest requestId="0005">
  <location id="1291" longitude="-93.2857" latitude="45.1705" requestTime="08 Feb 2017 15:00"/>
</trafficSpeedRequest>

このリクエストからのレスポンスは次のようになります。 

<trafficSpeedResponse requestId="0005" unit="mph">
	<edgeResponse locationId="1291" edgeId="-20190321" speedLimit="24.9" 
		requestTime="08 Feb 2017 15:00" trafficSpeed="16.0"/>
</trafficSpeedResponse>

つまり、2017年2月5日15:00 (3 pm)に、そのエッジの平均速度は16.0マイル/時間でした。

例14-24 走行速度リクエスト(複数の場所)

この例は、それぞれが独自の場所IDを持ち、経度/緯度ペアによって指定され、リクエスト時間を指定している3つの場所での走行速度に関するバッチ・リクエストです。

<trafficSpeedRequest requestId="0006" unit="kmph">
	<location id="1291" longitude="-93.2857" latitude="45.1705" requestTime="08 Feb 2017 15:00"/>
	<location id="211" longitude="-93.24049" latitude="46.69592" requestTime="09 Feb 2017 10:00"/>
	<location id="42" longitude="-103.31349" latitude="20.6308" requestTime="10 Feb 2017 09:00"/>
</trafficSpeedRequest>

このリクエストからのレスポンスは次のようになります。 

<trafficSpeedResponse requestId="0006" unit="kmph">
	<edgeResponse locationId="1291" edgeId="-20190321" speedLimit="40.0"
		requestTime="08 Feb 2017 15:00" trafficSpeed="26.0"/>
	<edgeResponse locationId="211" edgeId="125949436" speedLimit="95.0" 
		requestTime="09 Feb 2017 10:00" trafficSpeed="79.0"/>
	<edgeResponse locationId="42" edgeId="-1073515692" speedLimit="20.0" 
		requestTime="10 Feb 2017 09:00" trafficSpeed="9.0"/>
</trafficSpeedResponse>

レスポンスには、リクエストされた各場所の<edgeResponse>要素が含まれています。つまり、場所ごとに、その場所に関連付けられている点(経度/緯度)での道路または通りについて指定日時の平均走行速度を戻します。

親トピック: WSServletでの走行速度のサポート

14.4.3.2 走行速度リクエストおよび走行速度レスポンスのスキーマ定義

走行速度リクエストのXMLスキーマ定義(XSD)は次のとおりです。 

<?xml version="1.0"  ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" >
	<xs:element name="trafficSpeedRequest">
		<xs:complexType>
			<xs:sequence>
				<xs:element maxOccurs="unbounded" name="location" type="locationType" />
			</xs:sequence>
			<xs:attribute name="requestId" type="xs:string" use="required"/>
			<xs:attribute name="requestType" type="xs:string" fixed="trafficSpeed"/>
			<xs:attribute name="unit" default="mph">
				<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value="mph"/>
						<xs:enumeration value="kmph"/>
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
		</xs:complexType>
	</xs:element>
</xs:schema>

この定義での<speedLimitRequest>の内容は次のとおりです。

  • requestId: リクエストのIDが含まれる文字列(必須属性)。

  • requestType: 固定値"trafficSpeed"が含まれる文字列(オプション属性)。この属性は、リクエストに指定する必要はなく、JSON解析で後で使用できるようにするためのものです。

  • unit: 速度単位が含まれる文字列(オプション属性)。"mph" (マイル/時間)および"kmph" (km/時間)のみがサポートされます。

  • location要素: 単一の場所または場所のリストを指定できます(「1つ以上の場所の指定」を参照)。

さらに、場所ごとに、走行速度リクエストには時間(requestTime)を指定する必要があります。時間の書式を指定しないと、デフォルトの"dd MMM yyyy HH:mm"が使用されます。

走行速度レスポンスのXMLスキーマ定義(XSD)は次のとおりです。 

<?xml version="1.0"  ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="trafficSpeedResponse">
		<xs:complexType>
			<xs:sequence>
				<xs:element maxOccurs="unbounded" name="edgeResponse">
					<xs:complexType>
						<xs:attribute name="locationId" type="xs:string"/>
						<xs:attribute name="edgeId" type="xs:long"/>
						<xs:attribute name="speedLimit" type="xs:double"/>
						<xs:attribute name="requestTime" type="xs:string"/>
						<xs:attribute name="trafficSpeed" type="xs:double"/>
						<xs:attribute name="error" type="xs:string"/>
					</xs:complexType>
				</xs:element>
			</xs:sequence>
			<xs:attribute name="requestId" use="required"/>
			<xs:attribute name="unit" default="mph">
				<xs:simpleType>
					<xs:restriction base="xs:string">
						<xs:enumeration value="mph"/>
						<xs:enumeration value="kmph"/>
					</xs:restriction>
				</xs:simpleType>
			</xs:attribute>
		</xs:complexType>
	</xs:element>
</xs:schema>

この定義での<trafficSpeedResponseの内容は次のとおりです。

  • requestId: リクエストのIDが含まれる文字列(必須属性)。

  • unit: 速度単位が含まれる文字列(オプション属性)。サポートされているのは、mph (マイル/時間)およびkmph (km/時間)のみです。デフォルトはmphです。

  • edgeResponse: 1つ以上の要素。単一のエッジまたはエッジのリストのいずれかです。次の属性があります。

    • locationId: 場所のIDが含まれる文字列。

    • edgeId: 入力場所の最も近いエッジのIDが含まれる文字列。

    • speedLimit: 制限速度。

    • requestTime: リクエスト時間が含まれる文字列。

    • trafficSpeed: 走行速度。

  • error: リクエストが正しくない場合に、エラー・メッセージが含まれる文字列。

親トピック: WSServletでの走行速度のサポート

14.4.4 WSServletの例外処理

入力XMLリクエストが正しくないまたは必要な値が欠落している場合、WSServletはXMLレスポンスに1つ以上の例外をスローします。

例外レスポンスのスキーマ定義は次のとおりです。

<?xml version="1.0"  ?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="RouteServerException"  type="xs:string"/>
</xs:schema>

例外がスローされると、処理フローは中断されるため、バッチ・リクエストを処理する際の効率が低下します。

WSServletの例外リスト

WSServletサーブレットでは次の例外をスローできます。

WSE-0001: Cannot parse your xml request
WSE-0002: Cannot traverse xml request doc
WSE-0003: WSServlet can only process speedLimitRequest and trafficSpeedRequest
WSE-0004: Database is not connected
WSE-0100: Speed Limit Request Proccessing Exception
WSE-0101: Speed Limit requestId is null
WSE-0102: Speed Limit requestId is empty
WSE-0300: Traffic Speed Request Proccessing Exception
WSE-0301: Traffic Speed requestId is null
WSE-0302: Traffic Speed requestId is empty

WSServletエラー・ケースの例

次に、エラー・ケースの例をいくつか示します。

例14-25 リクエスト解析エラー

<?xml version="1.0" encoding="UTF-8"?>
<RouteServerException>[WSE-0001: Cannot parse your xml request]</RouteServerException>

例14-26 場所IDなし

<speedLimitRequest requestId="1" unit="mph">
	<location id="1291" longitude="-93.2857" latitude="45.1705"/>
	<location longitude="-93.24049" latitude="46.69592"/>
	<location id="376" longitude="-71.46006" latitude="42.71004"/>
</speedLimitRequest>

このバッチ制限速度リクエストでは3つの異なる場所を指定しています。2つ目の場所要素に必須のIDがありませんが、このエラーは、リクエストの他の場所には影響しません。

例14-27 その他の場所入力エラー

<speedLimitResponse requestId="1" unit="mph">
	<edgeResponse locationId="1291" edgeId="-20190321" speedLimit="24.85"/>
	<edgeResponse error="No location id."/>
	<edgeResponse locationId="376" edgeId="22325991" speedLimit="12.43"/>
</speedLimitResponse>

その他のエラーには、無効な場所の入力や、データベース表に結果が存在しない、走行速度リクエストにリクエスト時間が入力されていないなどがあります。

例14-28 エッジなし

<speedLimitResponse requestId="1" unit="mph">
	<edgeResponse locationId="1291" edgeId="-20190321" speedLimit="24.85"/>
	<edgeResponse locationId="211" edgeId="125949436" speedLimit="59.03"/>
	<edgeResponse locationId="376" error="Invalid location input."/>
</speedLimitResponse>

このバッチ制限速度レスポンスでは、3つ目のedgeResponseに「場所の入力が無効です。」というエラーがあります。これは、データベース問合せで表のエッジが微調整されなかった、つまり、場所の入力がそのデータ・セットによってカバーされていないために発生しています。

例14-29 バッチ・レスポンスでの複数のエラー

<trafficSpeedResponse requestId="1" unit="mph">
	<edgeResponse locationId="11" edgeId="-20190321" speedLimit="24.85" 
		requestTime="08 Feb 2017 15:00" trafficSpeed="16.0"/>
	<edgeResponse locationId="92" error="Invalid location input."/>
	<edgeResponse locationId="42" edgeId="-1073515692" speedLimit="12.43" error="No request time."/>
	<edgeResponse locationId="561" edgeId="22325991" speedLimit="12.43" error="No traffic speed data."/>
</trafficSpeedResponse>

このバッチ走行速度レスポンスには、複数のエラーがあります。

  • 2つ目のedgeResponseの場所92では、エラー"Invalid location input"が発生しています。

  • 3つ目のedgeResponseの場所42では、リクエストでrequestTimeが指定されていないため、エラー"No request time"が発生しています。

  • 4つ目のedgeResponseの場所561では、requestTimeが無効であるか、または走行速度データが表に存在しないため、エラー"No traffic speed data"が発生しています。

親トピック: WSServlet XML APIを使用した場所ベースの問合せ