This section explains how to submit route requests in XML format to the routing engine, and it describes the XML Schema Definitions (XSDs) for the route requests (input) and responses (output). XML is widely used for transmitting structured documents using the 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 routing engine servlet has the following format:
http://hostname:port/route-server-servlet-path?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.
route-server-servlet-path is the routing engine servlet path (for example, routeserver/servlet/RouteServerServlet).
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.
In a simple route request, you must specify a route ID, and you can specify one or more of the following attributes:
route_preference: fastest or shortest (default)
road_preference: highway (default) or local
return_driving_directions (whether to return driving directions): true or false (default)
return_hierarchical_directions (whether to return hierarchical directions): true or false (default)
return_locations (return geocoded results for the start and end locations of the route and any subroutes): true or false (default)
return_subroutes (whether to return subroutes): true (default if a multi-address route, ignored for a single-address route) or false
return_route_geometry (whether to return the line string coordinates for the route): true or false (default)
return_subroute_geometry (whether to return the line string coordinates for each subroute): true or false (default for multi-address routes)
return_segment_geometry (whether to return the line string coordinates for each maneuver in the route): true or false (default)
return_detailed_geometry: true (default; returns detailed geometries) or false (returns generalized geometries)
language: language used to generate driving directions (ENGLISH (default), FRENCH, GERMAN, ITALIAN, or SPANISH)
distance_unit: kilometer, mile (default), or meter
length_unit: us for feet (default) or metric for meters
time_unit: hour, minute (default), or second
weight_unit: us for tons (default) or metric for metric tons
pre_geocoded_locations (whether the start and end locations are input locations (address specifications or points) or previously geocoded locations): true (previously geocoded locations) or false (default; input locations)
driving_directions_detail: high, medium (default) or low
optimize_route: true or false (default)
route_type: open (default) or closed
vehicle_type: auto (default) or truck
truck_type: delivery, public, resident, or trailer; (no default)
truck_height: floating-point number in length_units
truck_length: floating-point number in length_units
truck_per_axle_weight: floating-point number in weight_units
truck_weight: floating-point number in weight_units
truck_width: floating-point number in length_units
Batched route requests are groups of one or more simple (single, multi-address, or TSP) requests encapsulated in a <batch_route_request> element. All attributes associated with the <batch_route_request> element are ignored. Because all encapsulated requests are simple requests, they use the preceding listed attributes.
In a batch mode route request, you must specify a request ID, a start ___location, and one or more end locations. Each ___location must have an ID attribute. Most of the attributes used for simple requests have no meaning for batch mode. You can use one or more of the following attributes in a batch mode route request, but using an attribute not in this list will cause an exception to be raised.
route_preference: fastest or shortest (default)
road_preference: highway (default) or local
distance_unit: kilometer, km, mile (default), or meter
time_unit: hour, minute (default), or second
sort_by_distance (whether to sort the returned routes in ascending order by distance of the end ___location from the start ___location): true or false (default)
cutoff_distance (returning only routes where the end ___location is less than or equal to a specified number of distance units from the start ___location): (number; default = no limit)
pre_geocoded_locations (whether the start and end locations are input locations (address specifications or points) or previously geocoded locations): true (previously geocoded locations) or false (default; input locations)
This section includes the following topics: