13 Routing Engine

The Spatial routing engine enables you to host an XML-based Web service that provides the following features:

  • For an individual route request (a start location and an end location): route information (driving distances, estimated driving times, and directions) between the two locations

  • For a batch route request (multiple routes, with the same start location but different end locations): route information (driving distance and estimated driving time) for each route

For any request, the start and end locations are identified by addresses, geocoded results, or longitude/latitude coordinates.

A route can be single-address, consisting of the start location and the end location, or multi-address, consisting of the start location, one or more intermediate locations, and the end location.

Multi-address routes are explained in Section 13.1.

The routing engine is implemented as a Java 2 Enterprise Edition (J2EE) Web application that you can deploy in an Oracle Weblogic Server, Oracle Application Server, or standalone Oracle Application Server Containers for J2EE (OC4J) environment.

Figure 13-1 shows the basic flow of action with the routing engine: a client locates a remote routing engine instance, sends a route request, and processes the route response returned by the routing engine instance.

Figure 13-1 Basic Flow of Action with the Spatial Routing Engine

Description of Figure 13-1 follows
Description of "Figure 13-1 Basic Flow of Action with the Spatial Routing Engine"

This chapter contains the following major sections:

13.1 Multi-Address Routing

A multi-address route contains one or more intermediate locations in addition to the start and end locations. A multi-address route thus contains subroutes: each subroute covers the path between two locations. A route or subroute contains one or more segments: each segment covers the path between two points along the route or subroute.

For example, assume you want to drive from your workplace to customer A, then to customer B, and then to customer C.

  • Your route has your workplace as the start location, customers A and B as intermediate locations, and customer C as the end location.

  • Your route has three subroutes: (1) workplace to customer A, (2) customer A to customer B, and (3) customer B to customer C.

  • Each subroute probably has multiple segments (each one associated with a specific driving direction step).

A multi-address route contains a <start_location> element, one or more <location> elements, and an <end_location> element. Several subroute-related attributes of these elements apply only to multi-address routing, for example, return_subroutes, return_subroute_edge_ids, and return_subroute_geometry. These elements and attributes are explained in Section 13.3.2.

In multi-address routing, the route that is returned has the locations in exactly the order specified in the request. Multi-address routing does not attempt to optimize the route for time or distance by rearranging the locations; specifically, it does not perform any TSP ("traveling salesperson problem") computations.

13.2 Deploying and Configuring the Routing Engine

To enable the routing engine to process routing requests and to generate responses, you must create a network (Oracle Database network data model network) on top of the routing data, and then deploy the routeserver.ear file using Oracle WebLogic Server, Oracle Application Server, or OC4J. This section describes the basic steps.

To create the network, follow these steps:

  1. If a network with the routing data already exists, drop it, to ensure that all structures are "clean" in the network to be created. To drop the existing network, execute a statement in the following form:

    EXECUTE SDO_ROUTER_PARTITION.DELETE_ROUTER_NETWORK('<log_file_name>', '<network_name>');

    <log_file_name> is the name of the log file that was specified in the call to SDO_ROUTER_PARTITION.DELETE_ROUTER_NETWORK to create the network to be dropped.

    <network_name> is the name of the network to be dropped.

    For example:

    EXECUTE SDO_ROUTER_PARTITION.DELETE_ROUTER_NETWORK('create_sf_net.log', 'ndm_sf_net');

  2. Create the network for the routing data by executing a statement in the following form:

    EXECUTE SDO_ROUTER_PARTITION.CREATE_ROUTER_NETWORK('<log_file_name>', '<network_name>');

    <log_file_name> is the name of the log file to use for this network.

    <network_name> is the name of the network to be created.

    For example:

    EXECUTE SDO_ROUTER_PARTITION.CREATE_ROUTER_NETWORK('create_sf_net.log', 'ndm_sf_net');

    The log file initially contains messages similar to the following:

    INFO: creating the Routeserver network: NDM_SF_NET
     creating indexes
     creating views
     generating metadata

To deploy and configure the routing engine, follow these steps:

  1. Add the following element inside the <web-site> element in your http-web-site.xml or default-web-site.xml file:

    <web-app application="routeserver" 
          name="web" 
          load-on-startup="true" 
          root="/routeserver" 
          max-inactivity-time="no shutdown" 
          shared="false" />

  2. Deploy the routing engine using Oracle WebLogic Server, Oracle Application Server, or OC4J:

    • Using Oracle WebLogic Server: Unpack the routeserver.ear file in your $ORACLE_HOME/md/jlib directory. Rename the routeserver.ear file and unpack its contents into a directory called ../routeserver.ear . Rename the web.war file now found under the $routeserver.ear/ directory and unpack its contents into a subdirectory called ../web.war . Your directory structure should therefore be $routeserver.ear/web.war/ .

      After unpacking the routeserver.ear and web.war files, copy the xmlparserv2.jar file in your $ORACLE_HOME/LIB/ directory into the $routeserver.ear/web.war/WEB-INF/lib/ directory.

      To deploy the routeserver.ear file, log on to the WLS console (for example, http://<hostname>:7001/console); and from Deployments, install the routeserver.ear file, accepting the name routeserver for the deployment and choosing the option to make the deployment accessible from a specified location.

    • Using Oracle Application Server or OC4J: Deploy the routeserver.ear file in your $ORACLE_HOME/md/jlib directory using the OracleAS or the standalone OC4J Application Server Control (for example, http://<hostname>:8888/em). You can deploy the routeserver.ear file in an existing OC4J instance, or you can create a new OC4J instance for the routing engine. In either case, enter routeserver for the Application Name during deployment.

  3. Launch the Oracle routing engine welcome page in a Web browser using the URL http://<hostname>:<port>/routeserver . On the welcome page, select the Administration link and enter the administrator (weblogic or oc4jadmin) user name and password.

    Note:

    If you are using WebLogic Server and if you are not using the default WebLogic administrator user name, you will need to edit the weblogic.xml file located in the $routeserver.ear/web.war/WEB-INF/ directory. Replace <principal-name>weblogic</principal-name> with your WebLogic Server administrator user name, for example, <principal-name>my_weblogic_admin</principal-name>.

  4. Limit the maximum number of concurrent requests (max-http-connections) value to 10. For example, with OC4J add the following element inside the <application-server> element in the server.xml file:

    <max-http-connections value="10" />

    It is important to limit the number of concurrent requests that the Oracle Route Server can process at any given time to prevent java.lang.OutOfMemoryError errors.

  5. Configure the web.xml file, as explained in Section 13.2.1, and save the changes.

  6. If you deployed to Oracle WebLogic Server or Oracle Application Server, restart the routing engine.

    If the welcome page is not displayed, ensure that the newly deployed routing engine service was successfully started. It is assumed that you are running WebLogic Server 10.3.1.0 or later with an Oracle Database Release 11.2 or later routeserver.ear file; or that you are running Oracle AS or OC4J 10.1.3 or later with an Oracle 11g or later routeserver.ear file.

  7. If you deployed to an OC4J instance, start OC4J using the following command options:

    -server 
-Xms<HEAP_SIZE>
-Xmx<HEAP_SIZE>
-XX:NewSize=<YOUNG_GENERATION_SIZE>
-XX:MaxNewSize=<YOUNG_GENERATION_SIZE>
-Dsun.rmi.dgc.server.gcInterval=3600000 
-Dsun.rmi.dgc.client.gcInterval=3600000
-verbose:gc  (optional)

    <HEAP_SIZE> must be at least 512 MB, and has a recommended size of at least 1024 MB (1 GB). Make sure that this memory is physical memory and not virtual memory.

    <YOUNG_GENERATION_SIZE> should be one-fourth (25%) of the <HEAP_SIZE> value.

    -verbose:gc will print all minor and major Java garbage collections. Monitoring these statistics could be useful for memory resource planning. If you find that garbage collections are occurring frequently or are lasting several seconds, you probably need to allocate more physical memory to the Java VM.

    Note:

    The amount of memory the Java VM will need depends mostly on two parameters: the <max-http-connections value="..." /> element in the <application-server> element in server.xml, and the partition_cache_size_limit parameter in web.xml.

    The following command is an example that starts OC4J. Note that the -config flag is an OC4J command line parameter, not a VM option.

    c:\jdk1.5.0_06\bin\java -server 
                        -Xms1024m 
                        -Xmx1024m 
                        -XX:NewSize=256m 
                        -XX:MaxNewSize=256m 
                        -Dsun.rmi.dgc.server.gcInterval=3600000 
                        -Dsun.rmi.dgc.client.gcInterval=3600000
                        -verbose:gc 
                        -jar c:\oc4j\j2ee\home\oc4j.jar 
                        -config c:\oc4j\j2ee\home\config\server.xml

  8. Verify your deployment by visiting the URL in the following format:

    http://<hostname>:<port>/routeserver

    You should see a welcome page. You should also see a message in the console window in which you started OC4J indicating that the Oracle Route Server was successfully initialized.

    If you do not see a welcome message, the route server is probably not configured properly to run in your environment. In this case, edit the <ROUTE_SERVER_HOME>/routeserver/web/WEB-INF/web.xml file to reflect your environment and your preferences. (The web.xml file is inside the routeserver.ear file, and it will not be visible until OC4J expands it into the route server directory structure under <ROUTE_SERVER_HOME>.) When you are finished editing, restart the routing engine or OC4J, and verify your deployment.

  9. Consult the supplied examples. The page http://<hostname>:<port>/routeserver/ has links at the bottom in a section named Test Samples. These examples demonstrate various capabilities of the Oracle Route Server. This is the best way to learn the XML API, which is described in Section 13.3.

13.2.1 Configuring the web.xml File

You will probably need to make some changes to the default web.xml file that is included with Spatial, especially if you want to use settings from an older web.xml file or if you want to specify a language or use long ID values. You may want to edit or add some of the following parameters.

The parameters and grouped and listed here in the order in which they appear in the web.xml file. See also the descriptive comments in the web.xml file.

Route Server initialization parameters:

  • routeserver_schema_jdbc_connect_string: Connect string to the database that contains routing data.

  • routeserver_schema_username: Name of the user that was created to access Oracle routing data.

  • routeserver_schema_password: Password for the user that was created to access Oracle routing data. You can obfuscate the password by preceding the password string with an exclamation point (!); if you do this, the password is obfuscated, and the web.xml file is rewritten the next time the routing engine is started.

  • routeserver_network_name: TBS??? Network name for the routing engine.

  • routeserver_schema_connection_cache_min_limit: Minimum number of database connections cached by the routing engine.

  • routeserver_schema_connection_cache_max_limit: Maximum number of database connections cached by the routing engine.

Geocoder parameters:

  • geocoder_type: Type of geocoder being used: httpclient HTTP client; interacts with the Java servlet), thinclient (thin client; interacts with the Oracle Database geocoder), or none (no geocoder is provided).

    If geocoder_type is thinclient and if the geocoder and the routing engine are in the same OC4J container, the geocoder must be configured to use a data source and to avoid connection pool conflicts.

    Depending on the value of this parameter, examine the settings in the HTTP Client or Thin Client section of the web.xml file, and make any edits as appropriate. For example, if you specified thinclient, you can obfuscate the Oracle geocoder password in the same way as with the routeserver_schema_password parameter.

  • Parameters used if geocoder_type = httpclient: geocoder_http_url, geocoder_http_proxy_host, geocoder_http_proxy_port

  • Parameters used if geocoder_type = thinclient: geocoder_schema_host, geocoder_schema_port, geocoder_schema_sid, geocoder_schema_username, geocoder_schema_password, geocoder_schema_mode

Logging parameters:

  • log_filename: Location (relative or absolute) and name of the log file.

  • log_level: Type (and amount) of information to be written to the log file. From least to most information: FATAL, ERROR, WARN, INFO, DEBUG, or FINEST (all messages).

  • log_thread_name: Whether to log the name of the thread that makes each entry.

  • log_time: Whether to include the time with each entry.

Road description parameters:

  • max_speed_limit: Maximum speed limit of any road segment, in meters per second. (34 meters per second is about 122 kilometers per hour or 75 miles per hour.)

  • local_road_threshold: A number of miles (default = 25, minimum = 10). If the estimated distance in miles between source and destination nodes is less than or equal to this value, local roads are considered as an option; if the distance is greater than this value, local roads are not considered.

    This parameter enables optimizations for short routes. Lower values can speed the routing engine performance by decreasing the size of the solution set to be searched, but can produce non-optimal short routes by causing the routing engine not to consider viable local road routes. Higher values (above the default of 25) can generate more accurate routes using local roads, but can slow the routing engine performance by increasing the size of the solution set to be searched.

  • highway_cost_multiplier: The amount by which to make highways less attractive when computing routes with route_preference set to local.

  • driving_side: R (the default) if traffic drives on the right side of the road, or L if traffic drives on the left side of the road.

  • language: Default language to use to produce driving directions. The supported languages are English (the default), French, German, Italian, and Spanish.

  • long_ids: TRUE (the default) causes ID values to have their length stored as LONG and not INTEGER data; FALSE causes ID values to have their length stored as INTEGER and not LONG data.

    If you have routing data that was partitioned using an Oracle Database release before 11.1, the long_ids parameter value must be FALSE until the data is repartitioned using a current release.

  • distance_function_type: geodetic for geodetic coordinate systems (such as SRID 8307 for longitude/latitude) or euclidean for projected coordinate systems.

Partitioning parameters:

  • partition_cache_size_limit: Maximum number of partitions that the network partition cache can hold. If partitions are already in the cache, the routing engine will not have to load them from the database; however, if you set this value too high, you can encounter an "out of memory" error.

  • partition_table_name: Name of the partition table that contains the network partitions. (The table is assumed to be in the schema associated with the routeserver_schema_jdbc_connect_string, routeserver_schema_username, and routeserver_schema_password parameters.)

13.3 Routing Engine XML API

This section explains how to submit route requests in XML format to the routing engine, and it describes the XML document type definitions (DTDs) 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 (as opposed to batch 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 the start and end locations of the route and any subroutes): true (default) or false

  • 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 if a multi-address route, ignored if a single-address route)

  • 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, FRENCH, GERMAN, ITALIAN, or SPANISH)

  • return_segment_edge_ids (whether to return the edge ID values of the edges of each maneuver in the route): true or false (default)

  • return_route_edge_ids (whether to return the edge ID values of the edges in the route): true or false (default)

  • return_subroute_edge_ids (whether to return the edge ID values of the edges in each subroute): true or false (default if a multi-address route, ignored if a single-address route)

  • distance_unit: kilometer, mile (default), or meter

  • time_unit: hour, minute (default), or second

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

In a batch route request, you must specify a request ID, a start location, and one or more end locations. Each location must have an ID attribute. You can also specify one or more of the following attributes for the batch route request:

  • route_preference: fastest or shortest (default)

  • road_preference: highway (default) or local

  • distance_unit: kilometer, 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 contains the following subsections:

13.3.1 Route Request and Response Examples

This section contains XML examples of route requests and the responses generated by those requests. One request uses specified addresses, another uses points specified by longitude and latitude coordinates, and another uses previously geocoded locations. For reference information about the available elements and attributes, see Section 13.3.2 for requests and Section 13.3.3 for responses.

Example 13-1 shows a request for the fastest route, preferably using highways, between two offices at specified addresses (in Waltham, Massachusetts and Nashua, New Hampshire), with driving directions for each segment, and using miles for distances and minutes for times.

Example 13-1 Route Request with Specified Addresses

<?xml version="1.0" standalone="yes"?>
<route_request 
          id="8" 
          route_preference="fastest"
          road_preference="highway" 
          return_driving_directions="true"
          distance_unit="mile" 
          time_unit="minute">
  <start_location>
    <input_location id="1">
      <input_address>
        <us_form1 
          street="1000 Winter St" 
          lastline="Waltham, MA" />
      </input_address>
    </input_location></start_location>
  <end_location>
    <input_location id="2">
      <input_address>
        <us_form1 
          street="1 Oracle Dr" 
          lastline="Nashua, NH" />
      </input_address>
    </input_location>
  </end_location>
</route_request>

Example 13-2 shows the response generated by the request in Example 13-1. (The output is reformatted for readability.)

Example 13-2 Route Response with Specified Addresses

<?xml version="1.0" encoding="UTF-8" ?>
<route_response>
  <route 
    id="8" 
    step_count="15" 
    distance="29.855655894643636" 
    distance_unit="mile" 
    time="34.41252848307292" 
    time_unit="minute">
  <segment 
    sequence="1" 
    instruction="Start out on WINTER ST (Going North)" 
    distance="0.6715170911787637" time="1.1257004737854004"/>
  <segment 
    sequence="2" 
    instruction="Turn SLIGHT RIGHT onto RAMP (Going Northwest)" 
    distance="0.05893317343308232" 
    time="0.09879287083943684"/>
  <segment 
    sequence="3" 
    instruction="Turn RIGHT onto OLD COUNTY RD (Going Northeast)" 
    distance="0.6890481152276999" 
    time="1.6801289876302083"/>
  <segment 
    sequence="4" 
    instruction="Turn RIGHT onto TRAPELO RD (Going Southeast)" 
    distance="1.0062739119153126" 
    time="1.686871592203776"/>
  <segment 
    sequence="5" 
    instruction="Turn LEFT onto RAMP (Going North)" 
    distance="0.3364944434303735" 
    time="0.5640838623046875"/>
  <segment 
    sequence="6" 
    instruction="Merge onto I-95/RT-128 (Going North)" 
    distance="4.775246959324318" 
    time="4.926156107584635"/>
  <segment 
    sequence="7" 
    instruction="Continue on I-95/RT-128" 
    distance="0.0" 
    time="0.0"/>
  <segment 
    sequence="8" 
    instruction="Stay STRAIGHT to go onto 32B/32A (Going East)" 
    distance="0.27138218577176415" 
    time="0.4549326578776042"/>
  <segment 
    sequence="9" 
    instruction="Take EXIT 32A toward LOWELL" 
    distance="0.043764782242279254" 
    time="0.07336527506510417"/>
  <segment 
    sequence="10" 
    instruction="Stay STRAIGHT to go onto RAMP (Going East)" 
    distance="0.2770620621155161" 
    time="0.4644541422526042"/>
  <segment 
    sequence="11" 
    instruction="Turn LEFT onto US-3 (Going Northwest)" 
    distance="20.664632308107564" 
    time="21.317686971028646"/>
  <segment 
    sequence="12" 
    instruction="Stay STRAIGHT to go onto EVERETT TPKE/US-3 (Going Northwest)" 
    distance="0.006080380444913938" 
    time="0.006272379557291667"/>
  <segment 
    sequence="13" 
    instruction="Take EXIT 1 toward SO NASHUA" 
    distance="0.550406717982974" 
    time="0.9226765950520833"/>
  <segment 
    sequence="14" 
    instruction="Turn LEFT onto SPIT BROOK RD (Going West)" 
    distance="0.5031617978313553" 
    time="1.0825419108072916"/>
  <segment 
    sequence="15" 
    instruction="Turn RIGHT onto ORACLE DR (Going North)" 
    distance="0.0016526518707758954" 
    time="0.00886537532011668"/>
  </route>
</route_response>

Example 13-3 shows a request for the fastest route, preferably using highways, between two locations specified as longitude/latitude points, with driving directions for each segment, and using meters for distances and seconds for times. (The points are associated with two locations in San Francisco, California: the World Trade Center and 100 Flower Street.)

Example 13-3 Route Request with Specified Longitude/Latitude Points

<?xml version="1.0" standalone="yes"?>
<route_request id="8" 
               route_preference="shortest"
               road_preference="highway" 
               return_driving_directions="true"
               distance_unit="meter" 
               time_unit="second"
               return_route_geometry="true"
          >
  <start_location>
     <input_location id="1" longitude="-122.39382" latitude="37.79518" />
  </start_location>
  <end_location>
     <input_location id="2" longitude="-122.4054826" latitude="37.7423566" />
  </end_location>
</route_request>

Example 13-4 shows the response generated by the request in Example 13-3. (The output is reformatted for readability.)

Example 13-4 Route Response with Specified Longitude/Latitude Points

?xml version="1.0" encoding="UTF-8" ?>
<route_response>
   <route id="8" step_count="11" distance="7196.72509765625" distance_unit="meter"
     time="521.2236328125" time_unit="second">
       <route_geometry>
         <LineString>
             <coordinates>
-122.39382,37.79518 -122.39382,37.79518 -122.39454,37.79601 -122.39467,37.79604 
-122.39476,37.79604 -122.39484,37.79599 -122.39486,37.79591 -122.39484,37.79579
-122.39462,37.79539 -122.39425,37.79491 -122.39389,37.79462 -122.39338,37.79433
-122.39326,37.79424 -122.39275,37.79384 -122.39263,37.79371 -122.39174,37.79293 
-122.39151,37.79274 -122.39142,37.79266 -122.3913,37.7925 -122.3912,37.79233 
-122.39102,37.79184 -122.39093,37.79161 -122.39072,37.79128 -122.39049,37.79104 
-122.39016,37.79076 -122.38878,37.78967 -122.38861,37.7895 -122.38839,37.7892
-122.38819,37.78877 -122.38813,37.78857 -122.38797,37.78783 -122.38796,37.78758 
-122.38801,37.78709 -122.38819,37.78478 -122.38832,37.78477 -122.38841,37.78474 
-122.38983,37.78361 -122.39127,37.78246 -122.39206,37.78184 -122.39261,37.78139 
-122.39319,37.78094 -122.3943,37.7801 -122.39486,37.77968 -122.39534,37.7793 
-122.39654,37.77833 -122.39876,37.77657 -122.39902,37.77639 -122.40033,37.77537 
-122.40096,37.77483 -122.40151,37.7744 -122.40205,37.77396 -122.40226,37.7738
 -122.40266,37.77349 -122.40321,37.77305 -122.40376,37.77262 -122.40543,37.77129 
-122.40578,37.77101 -122.40599,37.77083 -122.40699,37.77006 -122.40767,37.76953 
-122.40774,37.76947 -122.40781,37.7694 -122.40786,37.76932 -122.40788,37.76922 
-122.40788,37.76913 -122.40786,37.76897 -122.40785,37.76883 -122.40779,37.76838 
-122.40767,37.7671 -122.40756,37.76577 -122.40743,37.76449 -122.40734,37.76321 
-122.40722,37.76193 -122.40709,37.76067 -122.40695,37.75937 -122.40678,37.75776 
-122.4067,37.75684 -122.40663,37.75617 -122.40647,37.75458 -122.40644,37.75428 
-122.40632,37.75299 -122.4062,37.75174 -122.40617,37.75138 -122.40614,37.75103 
-122.40606,37.75066 -122.40565,37.74987 -122.40529,37.74937 -122.40518,37.74924 
-122.40506,37.74913 -122.4045,37.74873 -122.4041,37.74845 -122.40393,37.74827 
-122.40384,37.74815 -122.40378,37.74801 -122.40375,37.74785 -122.40381,37.74762 
-122.40397,37.74719 -122.4043,37.74633 -122.40434,37.74618 -122.40434,37.74603 
-122.40431,37.74594 -122.4042,37.74554 -122.40416,37.7453 -122.40417,37.74515 
-122.40431,37.74464 -122.40445,37.74427 -122.40461,37.74393 -122.40479,37.74362 
-122.40522,37.74304 -122.40482,37.74282 -122.40517,37.74233 
-122.40545613036156,37.742431337836386 
          </coordinates>
        </LineString>
      </route_geometry>
      <segment sequence="1" instruction="Start out on FERRY BLDG/FERRY
         PLZ/HERB CAEN WAY/THE EMBARCADERO (Going Northwest)"
         distance="111.84008026123047" time="6.990005016326904"/>
      <segment sequence="2" instruction="Turn LEFT onto RAMP (Going 
        Southwest)" distance="51.30750274658203" time="4.664318561553955"/>
      <segment sequence="3" instruction="Turn LEFT onto HERB CAEN 
         WAY/THE EMBARCADERO (Going Southeast)" 
          distance="902.3695068359375" time="56.39809036254883"/>
      <segment sequence="4" instruction="Turn SLIGHT RIGHT onto THE
         EMBARCADERO (Going Southeast)" distance="534.7628173828125"
         time="33.42267608642578"/>
      <segment sequence="5" instruction="Turn RIGHT onto BRANNAN ST 
          (Going Southwest)" distance="2454.0565185546875"
          time="219.57013702392578"/>
      <segment sequence="6" instruction="Turn SLIGHT LEFT onto POTRERO AVE
         (Going South)" distance="2066.54541015625" time="129.15908813476562"/>
      <segment sequence="7" instruction="Turn SLIGHT LEFT onto BAY SHORE 
          BLVD (Going Southeast)" distance="747.060546875"
          time="46.6912841796875"/>
      <segment sequence="8" instruction="Stay STRAIGHT to go onto BAY SHORE
         BLVD/BAYSHORE BLVD (Going South)" distance="195.7578125"
         time="12.23486328125"/>
      <segment sequence="9" instruction="Turn LEFT onto OAKDALE AVE 
         (Going Southeast)" distance="42.8857421875" time="3.898712158203125"/>
      <segment sequence="10" instruction="Turn RIGHT onto PATTERSON ST 
          (Going Southwest)" distance="62.525390625" time="5.68414306640625"/>
      <segment sequence="11" instruction="Turn RIGHT onto FLOWER ST (Going
         West)" distance="27.61372947692871" time="2.5103390216827393"/>
   </route>
</route_response>

Example 13-5 shows a request for the route, with driving directions, where the start and end locations are previously geocoded locations that are about one-half mile apart in Boston, Massachusetts.

Example 13-5 Route Request with Previously Geocoded Locations

<?xml version="1.0" standalone="yes"?>
<route_request id="8" 
               route_preference="shortest"
               road_preference="highway" 
               return_driving_directions="true"
               distance_unit="mile" 
               time_unit="minute"
               pre_geocoded_locations="true">
    <start_location>
        <pre_geocoded_location id="1">
            <edge_id>22161661</edge_id>
            <percent>.5</percent>
            <side>L</side>
        </pre_geocoded_location>
    </start_location>
    <end_location>
        <pre_geocoded_location id="2">
            <edge_id>22104391</edge_id>
            <percent>.5</percent>
            <side>R</side>
        </pre_geocoded_location>
    </end_location>
</route_request>

Example 13-6 shows the response to the request in Example 13-5. (The output is reformatted for readability.)

Example 13-6 Route Response with Previously Geocoded Locations

<?xml version="1.0" encoding="UTF-8" ?>
<route_response>
  <route 
     id="8" 
     step_count="5" 
     distance="0.6193447379707987" 
     distance_unit="mile" 
     time="1.6662169138590495" 
     time_unit="minute">
    <segment 
       sequence="1"
       instruction="Start out on HUNTINGTON AVE (Going Southeast)" 
       distance="0.0059065276259536855" 
       time="0.01440208355585734"/>
    <segment 
       sequence="2" 
       instruction="Turn LEFT onto AVENUE OF THE ARTS/HUNTINGTON AVE/RT-9 (Going Northeast)"              distance="0.020751234891437903" 
       time="0.050598426659901934"/>
    <segment        sequence="3" 
       instruction="Turn RIGHT onto PUBLIC ALLEY 405 (Going Southeast)" 
       distance="0.053331456545578096" 
       time="0.286087703704834"/>
    <segment        sequence="4" 
       instruction="Turn RIGHT onto ST BOTOLPH ST (Going Southwest)" 
       distance="0.028921701076542888" 
       time="0.07052075068155925"/>
    <segment        sequence="5" 
       instruction="Turn RIGHT onto MASSACHUSETTS AVE (Going Northwest)" 
       distance="0.5104338249425094" 
       time="1.2446078459421794"/>
  </route>
</route_response>

13.3.2 Route Request DTD

The following is the complete DTD for a route request. The main elements and attributes of the DTD are explained in sections that follow.

<?xml version="1.0" encoding="UTF-8"?>
<!-- geocoder.dtd includes gmlfeature.dtd. These define the 
     ELEMENTS input_address and those in Feature, FeatureMember,
     and FeatureCollection that are used in geoFeature, 
     geoFeatureCollection, and geoFeatureMember.
-->
<!ENTITY % GEOCODERDTD SYSTEM "geocoder.dtd">
%GEOCODERDTD;
 
<!—
   input_location: specify an input address to the geocoder
   input_address: specify a location using a street address
   Point: specify a location using its longitude/latitude
 
   (The input_location, input_address and Point elements are defined in
   geocoder.dtd. GeometryClasses is defined in gmlgeometry.dtd.)
-->
<!ELEMENT route_request (start_location, location*, end_location)>
<!ATTLIST route_request 
      vendor CDATA "Oracle"
      id CDATA #REQUIRED
      route_preference (FASTEST|SHORTEST) #IMPLIED
      road_preference (HIGHWAY|LOCAL) #IMPLIED
      return_driving_directions (TRUE|FALSE) #IMPLIED
      return_hierarchival_driving_directions (TRUE|FALSE) #IMPLIED
      return_locations (TRUE|FALSE) #IMPLIED
      return_subroutes (TRUE|FALSE) #IMPLIED
      return_route_geometry (TRUE|FALSE) #IMPLIED
      return_subroute_geometry (TRUE|FALSE) #IMPLIED
      return_segment_geometry (TRUE|FALSE) #IMPLIED
      return_detailed_geometry (TRUE|FALSE) #IMPLIED
      return_route_edge_ids (TRUE|FALSE) #IMPLIED
      return_subroute_edge_ids (TRUE|FALSE) #IMPLIED
      return_route_segment_ids (TRUE|FALSE) #IMPLIED
      language (ENGLISH|FRENCH|GERMAN|ITALIAN|SPANISH) #IMPLIED
      distance_unit (KM|MILE|METER) #IMPLIED
      time_unit (HOUR|MINUTE|SECOND) #IMPLIED
      pre_geocoded_locations (TRUE|FALSE) #IMPLIED>
      driving_directions_detail (LOW|MEDIUM|HIGH) #IMPLIED
 
<!-- The following are alternatives for specifying the location. Use 
     input_location when you want to represent a location with a  
     street address (input_address) or longitude/latitude (Point).
     If you have already geocoded the location, 
     you can use information from the geocoder response to 
     construct a pre_geocoded_location element. 
     The geocoder returns:
         - An edge_id (integer that is the road segment identifier)
         - A side ('L' or 'R' – left or right side)
         - A percent (floating-point number 0.0 to 1.0 representing  
           the fraction of the length from the start of the road 
           segment to this location.
-->
<!ELEMENT pre_geocoded_location (edge_id, percent, side)>
<!ATTLIST pre_geocoded_location id CDATA #REQUIRED>
 
 
<!ELEMENT start_location (input_location|pre_geocoded_location|)>
<!ELEMENT location (input_location|pre_geocoded_location|)>
<!ELEMENT end_location (input_location|pre_geocoded_location|)>

13.3.2.1 route_request Element

The <route_request> element has the following definition:

<!ELEMENT route_request (start_location, location*, end_location)>

The root element of a route request is always named route_request.

The <start_location> child element specifies the start location for the route, as an address specification, a geocoded address, or longitude/latitude coordinates.

The <location> child element specifies a location for a segment, as an address specification, a geocoded address, or longitude/latitude coordinates. If there are no <location> elements, it is a single-address route; if there are one or more <location> elements, it is a multi-address route.

The <end_location> child element specifies the end location for the route, as an address specification, a geocoded address, or longitude/latitude coordinates.

In a route request:

  • If <start_location> is an address specification or longitude/latitude coordinates, each <end_location> and <location> element can be either an address specification or longitude/latitude coordinate; however, it cannot be a geocoded address.

  • If <start_location> is a geocoded address, <end_location> and any <location> specifications must be geocoded addresses.

13.3.2.2 route_request Attributes

The root element <route_request> has a number of attributes, most of them optional. The attributes are defined as follows:

<!ATTLIST route_request 
      vendor CDATA "Oracle"
      id CDATA #REQUIRED
      route_preference (FASTEST|SHORTEST) #IMPLIED
      road_preference (HIGHWAY|LOCAL) #IMPLIED
      return_driving_directions (TRUE|FALSE) #IMPLIED
      return_hierarchival_driving_directions (TRUE|FALSE) #IMPLIED
      return_locations (TRUE|FALSE) #IMPLIED
      return_subroutes (TRUE|FALSE) #IMPLIED
      return_route_geometry (TRUE|FALSE) #IMPLIED
      return_subroute_geometry (TRUE|FALSE) #IMPLIED
      return_segment_geometry (TRUE|FALSE) #IMPLIED
      return_detailed_geometry (TRUE|FALSE) #IMPLIED
      return_route_edge_ids (TRUE|FALSE) #IMPLIED
      return_subroute_edge_ids (TRUE|FALSE) #IMPLIED
      return_route_segment_ids (TRUE|FALSE) #IMPLIED
      language (ENGLISH|FRENCH|GERMAN|ITALIAN|SPANISH) #IMPLIED
      distance_unit (KM|MILE|METER) #IMPLIED
      time_unit (HOUR|MINUTE|SECOND) #IMPLIED
      pre_geocoded_locations (TRUE|FALSE) #IMPLIED>
      driving_directions_detail (LOW|MEDIUM|HIGH) #IMPLIED

vendor is an optional attribute whose default value identifies the routing provider as Oracle.

id is a required attribute that specifies an identification number to be associated with the request.

route_preference is an optional attribute that specifies whether you want the route with the lowest estimated driving time (FASTEST) or the route with the shortest driving distance (SHORTEST, the default).

road_preference is an optional attribute that specifies whether you want the route to use highways (HIGHWAY, the default) or local roads (LOCAL) when a choice is available.

return_driving_directions is an optional attribute that specifies whether you want driving directions for the route. TRUE returns driving directions; FALSE (the default) does not return driving directions.

return_hierarchical_driving_directions is an optional attribute that specifies whether you want driving directions for the route returned in an expandable and collapsible hierarchy. TRUE returns driving directions in an expandable and collapsible hierarchy; FALSE (the default) returns driving directions in a list with no hierarchy.

return_locations is an optional attribute that specifies whether to return the start and end locations of the route and any subroutes. TRUE (the default) returns these locations; FALSE does not return these locations.

return_subroutes is an optional attribute that specifies whether to return subroutes is a multi-address route. TRUE (the default for multi-address routes) returns subroutes; FALSE does not return subroutes. (This attributed is ignored for single-address routes.)

return_route_geometry is an optional attribute that specifies whether you want the coordinates of each line string that represents a maneuver in the route. TRUE returns the coordinates; FALSE (the default) does not return the coordinates.

return_subroute_geometry is an optional attribute that specifies whether you want the coordinates of each line string that represents a maneuver in each subroute. TRUE returns the coordinates; FALSE (the default for multi-address routes) does not return the coordinates. (This attributed is ignored for single-address routes.)

return_segment_geometry is an optional attribute that specifies whether you want the coordinates of the line string that represents the route. TRUE returns the coordinates; FALSE (the default) does not return the coordinates. If return_segment_geometry is TRUE, driving directions for the route are returned regardless of the value of the return_route_geometry attribute.

return_detailed_geometry is an optional attribute that indicates the level of detail to be included in returned geometries. TRUE (the default) returns detailed geometries; FALSE returns generalized geometries (usually with fewer coordinates).

return_route_edge_ids is an optional attribute that specifies whether you want the edge ID values of the edges in the route. TRUE returns the edge ID values; FALSE (the default) does not return the edge ID values.

return_subroute_edge_ids is an optional attribute that specifies whether you want the edge ID values of the edges in the subroutes. TRUE returns the edge ID values; FALSE (the default for multi-address routes) does not return the edge ID values. (This attributed is ignored for single-address routes.)

return_segment_edge_ids is an optional attribute that specifies whether you want the edge ID values of the edges of all maneuvers in the route. TRUE returns the edge ID values; FALSE (the default) does not return the edge ID values. If return_segment_edge_ids is TRUE, edge ID values are returned regardless of the value of the return_route_edge_ids attribute.

language is an optional attribute that overrides the default language used to generate the driving directions. The default language for is set in the web.xml file; you can use this attribute to override the default on a per-request basis. The following attribute values are supported: ENGLISH, FRENCH, GERMAN, ITALIAN, and SPANISH.

distance_unit is an optional attribute that specifies the unit of measure for distance values that are returned: KM for kilometer, MILE (the default) for mile, or METER for meter.

time_unit is an optional attribute that specifies the unit for time values that are returned: HOUR for hour, MINUTE (the default) for minute, or SECOND for second.

pre_geocoded_locations is an optional attribute that indicates how the start and end locations are specified. TRUE means that both are previously geocoded locations specified using the <pre_geocoded_location> element; FALSE (the default) means that both are addresses specified using the <input_location> element.

driving_directions_detail is an optional attribute that influences the level of detail and the number of separate steps in driving instructions. The available values are HIGH (most details and steps), MEDIUM (the default), and LOW (fewest details and steps). For example, LOW might treat a segment as a single step even if it involves slight maneuvers to the right or left. The effect of a value for this attribute on the length of returned driving directions will vary, depending on the exact names of elements and maneuvers. This attribute is ignored if you do not specify TRUE for return_driving_directions or return_hierarchical_driving_directions.

Note:

The default level of detail changed in Oracle Database release 11.1, to provide fewer details and steps than before. If you want to have the same level of detail as in a previous release that did not have the driving_directions_detail attribute, specify HIGH for the driving_directions_detail attribute.

13.3.2.3 input_location Element

The <input_location> element specifies an address in a format that satisfies the Oracle Spatial geocoding request DTD, which is described in Section 11.7.2. You can specify the input location using either the <Point> element or the <input_address> element. Example 13-1 in Section 13.3.1 shows the start and end addresses specified using the <input_location> element and its child element <input_address>.

To use the <input_location> element, you must ensure that the value of the pre_geocoded_locations attribute is FALSE (the default) in the <route_request> element. You can use the <Point> and <input_address> elements together in a request.

13.3.2.4 pre_geocoded_location Element

The <pre_geocoded_location> element specifies a geocoded location in terms of how far along a street (an edge) the address is and on which side of the street. Example 13-5 in Section 13.3.1 shows the start and end addresses specified using the <pre_geocoded_location> element.

To use the <pre_geocoded_location> element, you must specify pre_geocoded_locations="TRUE" in the <route_request> element, and you must use the <pre_geocoded_location> element to specify both the start and end locations.

13.3.3 Route Response DTD

The following is the complete DTD for a route response:

<?xml version="1.0" encoding="UTF-8"?>
<!-- route_response DTD includes the gmlgeometry DTD 
     as an external entity reference.
     -->
<!ENTITY % GMLGEOMETRYDTD SYSTEM "gmlgeometry.dtd">
  %GMLGEOMETRYDTD;
 
<!ELEMENT route_response (route | router_error)>
 
<!ELEMENT route (route_geometry?, segment+)>
<!ATTLIST route id CDATA #REQUIRED
                step_count CDATA #IMPLIED
                time CDATA #IMPLIED
                distance CDATA #IMPLIED>
           
<!ELEMENT router_error EMPTY>
<!ATTLIST router_error 
                 id CDATA #REQUIRED
                 error_code CDATA #IMPLIED 
                 error_msg CDATA #IMPLIED>
 
<!ELEMENT route_geometry (LineString | MultiLineString)?>
 
<!ELEMENT route_edge_ids (EdgeIDs)?>
 
<!ELEMENT segment segment*, (LineString | MultiLineString)?>
<!ATTLIST segment sequence CDATA #REQUIRED
                  instruction CDATA #IMPLIED
                  time CDATA #IMPLIED
                  distance CDATA #IMPLIED>
 
<!ELEMENT segment_geometry (LineString | MultiLineString)?>
 
<!ELEMENT segment_edge_ids (EdgeIDs)?>

13.3.4 Batch Route Request and Response Examples

This section contains XML examples of batch route requests and the responses generated by those requests. One request uses specified addresses, and the other request uses previously geocoded locations. For reference information about the available elements and attributes, see Section 13.3.5 for requests and Section 13.3.6 for responses.

Example 13-7 shows a batch route request using specified addresses. The request is for the fastest routes, preferably using highways, between an office in Waltham, Massachusetts and three end locations (an Oracle office in Nashua, New Hampshire; the town offices in Concord, Massachusetts; and Boston City Hall), using miles for distances and minutes for times. The request calls for the returned routes to be sorted by distance between the start and end location, and for no routes over 35 miles to be returned.

Example 13-7 Batch Route Request with Specified Addresses

<?xml version="1.0" standalone="yes"?>
<batch_route_request 
          id="8" 
          route_preference="fastest"
          road_preference="highway" 
          return_driving_directions="false"
          sort_by_distance = "true" 
          cutoff_distance="35" 
          distance_unit="mile" 
          time_unit="minute">
  <start_location>
    <input_location 
          id="1">
      <input_address>
        <us_form1 
          street="1000 Winter St" 
          lastline="Waltham, MA" />
      </input_address>
    </input_location>
  </start_location>
  <end_location>
    <input_location id="10">
      <input_address>
        <us_form1 
          street="1 Oracle Dr" 
          lastline="Nashua, NH" />
      </input_address>
    </input_location>
  </end_location>
  <end_location>
    <input_location 
          id="11">
      <input_address>
        <us_form1 
          street="22 Monument Sq" 
          lastline="Concord, MA" />
      </input_address>
    </input_location>
  </end_location>
  <end_location>
    <input_location 
          id="12">
      <input_address>
        <us_form1 
          street="1 City Hall Plaza" 
          lastline="Boston, MA" />
      </input_address>
    </input_location>
  </end_location>
</batch_route_request>

Example 13-8 shows the response generated by the request in Example 13-7. (The output is reformatted for readability.)

Example 13-8 Batch Route Response with Specified Addresses

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<batch_route_response 
      id="8">
  <route 
    id="11" 
    step_count="0" 
    distance="6.637544152543032" 
    distance_unit="mile" 
    time="10.53597412109375" 
    time_unit="minute" />
  <route 
    id="12" 
    step_count="0" 
    distance="17.204805418116575" 
    distance_unit="mile"
    time="24.47645467122396" 
    time_unit="minute" />
  <route 
    id="10" 
    step_count="0" 
    distance="29.855655894643636" 
    distance_unit="mile" 
    time="34.41252848307292" 
    time_unit="minute" />
</batch_route_response>

Example 13-9 shows a batch route request using previously geocoded locations. The request is for the shortest routes, preferably using highways, between one location and three other locations, using miles for distances and minutes for times. The request calls for the returned routes to be sorted by distance between the start and end location, and for no routes over 50 miles to be returned.

Example 13-9 Batch Route Request with Previously Geocoded Locations

<?xml version="1.0" standalone="yes"?>
<batch_route_request id="8" 
                     route_preference="shortest"
                     road_preference="highway" 
                     return_driving_directions="false"
                     distance_unit="mile" 
                     time_unit="minute"
                     pre_geocoded_locations="true"
                     cutoff_distance="50"
                     sort_by_distance="true">
    <start_location>
        <pre_geocoded_location id="1">
            <edge_id>22161661</edge_id>
            <percent>.5</percent>
            <side>L</side>
        </pre_geocoded_location>
    </start_location>
    <end_location>
        <pre_geocoded_location id="2">
            <edge_id>22104391</edge_id>
            <percent>.5</percent>
            <side>R</side>
        </pre_geocoded_location>
    </end_location>
    <end_location>
        <pre_geocoded_location id="3">
            <edge_id>22160808</edge_id>
            <percent>.5</percent>
            <side>L</side>
        </pre_geocoded_location>
    </end_location>
    <end_location>
        <pre_geocoded_location id="4">
            <edge_id>22325991</edge_id>
            <percent>.5</percent>
            <side>R</side>
        </pre_geocoded_location>
    </end_location>
</batch_route_request>

Example 13-10 shows the response to the request in Example 13-9. Only two routes are returned, because the third route is longer than the specified cutoff distance of 50 miles. (The output is reformatted for readability.)

Example 13-10 Batch Route Response with Previously Geocoded Locations

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<batch_route_response 
      id="8">
  <route
    id="2" 
    step_count="0" 
    distance="0.6193447379707987" 
    distance_unit="mile" 
    time="1.6662169138590495" 
    time_unit="minute" />
  <route 
    id="4" 
    step_count="0" 
    distance="41.342018851363946" 
    distance_unit="mile" 
    time="47.95714518229167" 
    time_unit="minute" />
</batch_route_response>

13.3.5 Batch Route Request DTD

The following is the complete DTD for a batch route request. The main elements and attributes of the DTD are explained in sections that follow.

<!ENTITY % GEOCODERDTD SYSTEM "geocoder.dtd">
%GEOCODERDTD;
<!-- input_location element is defined in geocoder.dtd -->
 
<!ELEMENT batch_route_request (start_location, end_location+)>
 <!ATTLIST batch_route_request
      vendor CDATA "Oracle"
      id CDATA #REQUIRED
      route_preference (FASTEST | SHORTEST ) #IMPLIED
      road_preference (HIGHWAY | LOCAL) #IMPLIED
      distance_unit (KM | MILE | METER ) #IMPLIED
      time_unit (HOUR | MINUTE | SECOND) #IMPLIED
      sort_by_distance (TRUE | FALSE) #IMPLIED
      cutoff_distance CDATA #IMPLIED>
          
<!-- The following are alternatives for specifying the location. Use 
     input_location when you want to represent a location with a  
     street address (input_address) or by longitude/latitude (Point).
     If you have already geocoded the location, 
     you can use information from the geocoder response to  
     construct a pre_geocoded_location element. 
     The geocoder returns:
         - an edge_id (integer that is the road segment identifier)
         - a side ('L' or 'R' – left or right side)
         - a percent (floating-point number 0.0 to 1.0 representing  
           the fraction of the length from the start of the road 
           segment to this location.
-->
<!ELEMENT pre_geocoded_location (edge_id, percent, side)>
<!ATTLIST pre_geocoded_location id CDATA #REQUIRED>
 
<!ELEMENT start_location (input_location|pre_geocoded_location)>
<!ELEMENT end_location (input_location|pre_geocoded_location)>
<!-- IMPORTANT VALIDITY CONSTRAINT: each of the input_location
     elements that are children of end_location MUST contain
     the id attribute.  Normally, the id attribute is optional.
     If an id is not present, an exception will result.
     Also, each id must be unique within a batch_route_request.
     Otherwise, the request will yield unpredictable results.
-->

13.3.5.1 batch_route_request Element

The <batch_route_request> element has the following definition:

<!ELEMENT batch_route_request (start_location, end_location+)>

The root element of a route request is always named batch_route_request.

The <start_location> child element specifies the start location for the route, as an address specification, a geocoded address, or longitude/latitude point.

Each of the one or more <end_location> child elements specifies the end location for the route, as an address specification, a geocoded address, or longitude/latitude point.

13.3.5.2 batch_route_request Attributes

The root element <batch_route_request> has a number of attributes, most of them optional. The attributes are defined as follows:

<!ATTLIST batch_route_request 
      vendor CDATA "Oracle"
      id CDATA #REQUIRED
      route_preference (FASTEST|SHORTEST) #IMPLIED
      road_preference (HIGHWAY|LOCAL) #IMPLIED
      distance_unit (KM|MILE|METER) #IMPLIED
      time_unit (HOUR|MINUTE|SECOND) #IMPLIED
      sort_by_distance (TRUE | FALSE) #IMPLIED
      cutoff_distance CDATA #IMPLIED>
      pre_geocoded_locations (TRUE|FALSE) #IMPLIED>

Most <batch_route_request> attributes have the same meaning as their counterpart <route_request> attributes, which are explained in Section 13.3.5.2. In addition, the sort_by_distance and cutoff_distance attributes do not apply to single route requests.

sort_by_distance is an optional attribute that specifies whether you want the routes returned in ascending order by distance of the end location from the start location. TRUE sorts the returned routes by distance; FALSE (the default) does not sort the returned routes by distance.

cutoff_distance is an optional attribute that causes routes to be returned only where the end location is less than or equal to a specified distance from the start location. By default, all routes are returned.

Note:

If a route is within the specified cutoff_distance value but would generate a <router_error> element in the response (see Section 13.3.6), the route is removed from the response and not shown.

13.3.6 Batch Route Response DTD

The following is the complete DTD for a batch route response:

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT batch_route_response (route | route_error)+ >
<!ATTLIST batch_route_response id CDATA #REQUIRED>
<!ELEMENT route EMPTY>
<!ATTLIST route 
       id CDATA #REQUIRED
       step_count CDATA #IMPLIED
       distance CDATA #IMPLIED
       distance_unit CDATA #IMPLIED
       time CDATA #IMPLIED
       time_unit CDATA #IMPLIED>
<!ELEMENT router_error EMPTY>
<!ATTLIST router_error 
       id CDATA #REQUIRED
       error_code CDATA #IMPLIED
       error_msg CDATA #IMPLIED>

13.4 Data Structures Used by the Routing Engine

Each database user of the routing engine must have the following tables in its schema:

  • EDGE

  • NODE

  • PARTITION

  • SIGN_POST

The EDGE and NODE tables store edge and node information about the street network used by the routing engine. To understand how edges and nodes are used to represent street segments, intersections, and other entities in a street network, you must be familiar with the Oracle Spatial network data model, which is described in Oracle Spatial Topology and Network Data Models Developer's Guide.

The following sections describe the tables used by the routing engine, in alphabetical order by table name.

13.4.1 EDGE Table

The EDGE table contains one row for each directed edge in a street network. Each street segment (a part of a road between two nodes) is an undirected edge that corresponds to one or more directed edges in the EDGE table. The EDGE table contains the columns shown in Table 13-1.

Table 13-1 EDGE Table

Column Name Data Type Description

EDGE_ID

NUMBER

Edge ID number.

START_NODE_ID

NUMBER

Node ID number of the start node of this edge.

END_NODE_ID

NUMBER

Node ID number of the end node of this edge.

PARTITION_ID

NUMBER

Partition ID number of the network partition that contains this edge.

FUNC_CLASS

NUMBER

Functional road class: a number from 1 through 5, with 1 indicating a large, high-speed, high-volume road, and each successive class generally smaller in size, speed, and volume. Class 2 roads have consistent speeds and are used to get traffic to and from class 1 roads. Class 3 roads have high volume and are used to connect class 2 roads. Class 4 roads move volumes of traffic between neighborhoods (for example, a busy main road in a city). Class 5 roads are all other roads (for example, a small, low-volume street in a neighborhood).

LENGTH

NUMBER

Length of this edge, in meters.

SPEED_LIMIT

NUMBER

Assigned speed limit for this edge, in meters per second.

GEOMETRY

SDO_GEOMETRY

Line string geometry representing this edge, with the coordinates ordered from the start node to the end node.

NAME

VARCHAR2(128)

Name of this edge.

DIVIDER

VARCHAR2(1)

A value of N indicates that the edge is not divided; other values indicate whether, where, and how turns are allowed on the divided edge. (The routing engine currently considers only whether the edge is divided or not.)

13.4.2 NODE Table

The NODE table contains one row for each node that is the start node or end node of one or more edges in the street network. A node often corresponds to an intersection (the intersection of two edges); however, a node can be independent of any intersection (for example, the end of a "dead end" or "no outlet" street). The NODE table contains the columns shown in Table 13-2.

Table 13-2 NODE Table

Column Name Data Type Description

NODE_ID

NUMBER

Node ID number.

GEOMETRY

SDO_GEOMETRY

Point geometry representing this node.

PARTITION_ID

NUMBER

Partition ID number of the network partition that contains this node.

13.4.3 PARTITION Table

The PARTITION table is generated by Oracle based on the contents of the EDGE and NODE tables. The PARTITION table contains the columns shown in Table 13-3.

Table 13-3 PARTITION Table

Column Name Data Type Description

PARTITION_ID

NUMBER

Partition ID number.

SUBNETWORK

BLOB

Part of the network included in this partition.

NUM_NODES

NUMBER

Number of nodes in this partition.

NUM_NON_BOUNDARY_EDGES

NUMBER

Number of edges in this partition that are edges that are completely contained within the partition.

NUM_OUTGOING_BOUNDARY_EDGES

NUMBER

Number of edges in this partition that start in this partition and terminate in another partition. (An edge cannot be in more that two partitions; for example, an edge cannot start in one partition, go through a second partition, and end in a third partition.)

NUM_INCOMING_BOUNDARY_EDGES

NUMBER

Number of edges in this partition that start in another partition and terminate in this partition. (An edge cannot be in more that two partitions; for example, an edge cannot start in one partition, go through a second partition, and end in a third partition.)

13.4.4 SIGN_POST Table

The SIGN_POST table stores sign information that is used to generate driving directions. For example, a sign might indicate that Exit 33A on US Route 3 South goes toward Winchester. A SIGN_POST row might correspond to a physical sign at an exit ramp on a highway, but it does not need to correspond to a physical sign. The SIGN_POST table contains the columns shown in Table 13-4.

Table 13-4 SIGN_POST Table

Column Name Data Type Description

FROM_EDGE_ID

NUMBER

Edge ID number of the edge to which this sign applies (for example, the street segment containing the exit ramp).

TO_EDGE_ID

NUMBER

Edge ID number of the edge to which this sign points (for example, the street segment to which the exit ramp leads).

RAMP

VARCHAR2(64)

Ramp text (for example, US-3 SOUTH).

EXIT

VARCHAR2(8)

Exit number (for example, 33A).

TOWARD

VARCHAR2(64)

Text indicating where the exit is heading (for example, WINCHESTER).