Location-Based Query Using the WSServlet XML API

WSServlet is a routing engine servlet for performing lightweight location based queries related to speed limit and traffic speed.

You submit requests in XML format using HTTP protocol. If an HTTP request (GET or POST method) is used, it is assumed the request has a parameter named xml_request whose value is a string containing the XML document for the request.

A request to the servlet has the following format:

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

In this format:

hostname is the network path of the server on which the routing engine is running.
port is the port on which the application server listens.
routeserver/ws/WSServlet is the directory of the servlet.
xml-request is the URL-encoded XML request submitted using the HTML GET or POST method.

The input XML is required for all requests. The output will be an XML document.

WSServlet takes the following different requests:

Speed Limit: return speed limit of the nearest edge of the location.
Traffic Speed: return average traffic speed of the nearest edge of the location.

Requests and responses in related topics are formatted, as needed, for readability.

Specifying One or More Locations

A request to the WSServlet servlet can specify a single location or multiple locations. A request specifying a single location has one <location> element; a request specifying multiple locations has multiple <location> elements and is called a batch request.

A request to the WSServlet servlet references the locationType type, an XML schema definition type that is used for specifying a single location or multiple locations, plus other related attributes. This type is defined as follows:

<?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>

This type includes the following:

id: a string containing the ID (identifier) value of the location (mandatory attribute).
longitude: a string containing the longitude of the location (mandatory attribute).
latitude: a string containing the latitude of the location (mandatory attribute).
requestTime: a string containing the request time. It should be follow the default time format(dd MMM yyyy HH:mm) or a customized format.
timeFormat: a string containing the request time format. The default value is"dd MMM yyyy HH:mm"; however, you can customize the time format, such as "yyyy/mm/dd HH:mm" or "mm-dd-yyyy HH:mm".

Speed Limit Support in WSServlet

This topic provides examples of requests and responses related to speed limit, and schema definitions for the request and response. A request and its corresponding response can be for a single location or multiple locations.

Speed Limit Request and Response Examples

Example: Speed Limit Request (Single Location)

This example shows a speed limit request specifying a single location using a location ID (location id="1291") and a longitude-latitude pair.

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

The response from this request might look like the following:

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

Because the request did not specify a speed unit, the servlet uses the default unit of miles per hour (mph). In this case, although the speed limit is actually posted as 40 kilometers per hour (kmph), the servlet converts it to mph (24.9) in the response. In order to have the response indicate kilometers per hour, the request must include unit="kmph".

Example: Speed Limit Request (Multiple Locatons)

This example is a batch request for speed limits at three locations, each with its own location ID and each specified by a longitude-latitude pair. The request specifies a unit of kilometers per hour (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>

The response from this request might look like the following:

<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>

The response includes an <edgeResponse> element for each requested location. That is, for each location, it returns the speed limit on the road or street at the point (longitude-latitude) associated with that location.

Speed Limit Request and Response Schema Definitions

The speed limit request XML schema definition (XSD) is as follows.

<?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>

In this definition, <speedLimitRequest> includes:

requestId: a string containing the ID of the request (mandatory attribute).
requestType: a string that has a fixed value "speedLimit" (optional attribute). This attribute does not need to be specified in the request, and is intended for possible later use with JSON parsing.
unit: a string containing the speed unit, optional attribute. Only “mph“(miles per hour) and “kmph“(kilometers per hour) are supported.
location elements: Can be a single location or a list of locations, as explained in Specifying One or More Locations.

The speed limit response XML schema definition (XSD) is as follows.

<?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>

In this definition, <speedLimitResponse> includes:

requestId: a string containing the ID of the request (mandatory attribute).
unit: a string containing the speed unit (optional attribute). Only mph (miles per hour) and kmph (kilometers per hour) are supported. The default is mph.
edgeResponse: one or more elements. Can be a single edge or a list of edges. It includes the following attributes:
- locationId: a string containing the ID of the location.
- edgeId: a string containing the id of the nearest edge of the input location.
- speedLimit: the speed limit.
error: a string containing an error message when the request is incorrect.

Traffic Speed Support in WSServlet

This topic provides examples of requests and responses related to traffic speed, and schema definitions for the request and response. A request and its corresponding response can be for a single location or multiple locations.

The API for traffic speed is similar to that for speed limit, the main difference being that a time (requestTime attribute) is required in the input.

Traffic Speed Request and Response Examples

Example: Traffic Speed Request (Single Location)

This example shows a traffic speed request specifying a single location using a location ID (locationId="1291"), a longitude-latitude pair, and a time for which you want the average traffic speed (requestTime="08 Feb 2017 15:00"). Because the specified time uses the default format of "dd MMM yyyy HH:mm", it is not necessary to specify the format in the request.

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

The response from this request might look like the following:

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

That is, on February 5, 2017 at 15:00 (3 pm), the average speed for that edge was 16.0 miles per hour.

Example: Traffic Speed Request (Multiple Locatons)

This example is a batch request for traffic speeds at three locations, each with its own location ID, each specified by a longitude-latitude pair, and each specifying a request time.

<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>

The response from this request might look like the following:

<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>

The response includes an <edgeResponse> element for each requested location. That is, for each location, it returns the average traffic speed at the specified date and time on the road or street at the point (longitude-latitude) associated with that location.

Traffic Speed Request and Response Schema Definitions

The traffic speed request XML schema definition (XSD) is as follows.

<?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>

In this definition, <speedLimitRequest> includes:

requestId: a string containing the ID of the request (mandatory attribute).
requestType: a string that has a fixed value "trafficSpeed" (optional attribute). This attribute does not need to be specified in the request, and is intended for possible later use with JSON parsing.
unit: a string containing the speed unit, optional attribute. Only “mph“(miles per hour) and “kmph“(kilometers per hour) are supported.
location elements: an be a single location or a list of locations, as explained in Specifying One or More Locations.

In addition, for each location, a traffic speed request must specify a time (requestTime). If you do not specify a format for the time, the default "dd MMM yyyy HH:mm" is used.

The traffic speed response XML schema definition (XSD) is as follows.

<?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>

In this definition, <trafficSpeedResponse includes:

requestId: a string containing the ID of the request (mandatory attribute).
unit: a string containing the speed unit (optional attribute). Only mph (miles per hour) and kmph (kilometers per hour) are supported. The default is mph.
edgeResponse: one or more elements. Can be a single edge or a list of edges. It includes the following attributes:
- locationId: a string containing the ID of the location.
- edgeId: a string containing the id of the nearest edge of the input location.
- speedLimit: the speed limit.
- requestTime: a string containing the request time.
- trafficSpeed: the traffic speed.
error: a string containing an error message when the request is incorrect.

WSServlet Exception Handling

When the input XML request is incorrect or missing necessary values, WSServlet will throw one or more exceptions in the XML response.

The exception response schema definition is as follows:

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

Throwing an exception breaks the processing flow, which decreases efficiency when handling batch requests.

WSServlet Exception List

The WSServlet servlet can throw the following exceptions.

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 Error Case Examples

The following are some examples of error cases.

Example: Request Parsing Error

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

Example: Missing Location 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>

This batch speed limit request specifies three different location. The second location element has no ID, which is required; however, this error does not affect the other locations in the request.

Example: Other Location Input Errors

<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>

Other errors includes invalid location input, result not existing in the database table, and no request time input in traffic speed request.

Example: Missing Edge

<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>

In this batch speed limit response, the third edgeResponse has the error "Invalid location input." This occurred because the database query did not fine the edge in the table, that is, the location input is not covered by the data set.

Example: Multiple Errors in Batch Response

<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>

This batch traffic speed response has several errors:

The second edgeResponse for location 92 has the error "Invalid location input".
The third edgeResponse for location 42 has the error "No request time" because it does not have requestTime in the request.
The fourth edgeResponse for location 561 has the error "No traffic speed data", because either the requestTime is invalid or the traffic speed data did not exist in the table.