Skip Headers
Oracle® Spatial User's Guide and Reference
10g Release 2 (10.2)

Part Number B14255-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

C Routing Engine

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

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

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

Figure C-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 C-1 Basic Flow of Action with the Spatial Routing Engine

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

This chapter contains the following major sections:

C.1 Installing and Configuring the Routing Engine

Detailed information about installing and configuring the routing engine is in the README.txt file provided with the routing engine kit, which is packaged as a file named sdo_routing.zip. This section describes just the basic steps.

  1. Click the link to download the kit at the Oracle Technology Network (OTN) Spatial software download page:

    http://www.oracle.com/technology/software/products/Spatial/

  2. After downloading the sdo_routing.zip file, open it and read the README.txt file.

  3. Ensure that you have the system requirements for installing and running the routing engine, as explained in the README.txt file. These requirements include Oracle Database release 10.1.0.2 or later, Java Runtime Environment 1.3.1 or later, Oracle Application Server Containers for J2EE (OC4J) 9.0.4.0 or later, and substantial available physical memory (at least 4 GB is recommended).

  4. Follow the installation instructions in the README.txt file.

C.2 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:

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

In an input route (as opposed to batch route) request, you must specify a route ID, and you can specify one or more of the following attributes:

In an input 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:

This section contains the following subsections:

C.2.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 C.2.2 for requests and Section C.2.3 for responses.

Example C-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 C-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 C-2 shows the response generated by the request in Example C-1. (The output is reformatted for readability.)

Example C-2 Route Response with Specified Addresses

<?xml version="1.0" ?>
<route_response>
  <route 
          id="8" 
          step_count="14" 
          distance="30.28667355371901" 
          distance_unit="mile" 
          time="35.02037760416667" 
          time_unit="minute">
    <segment 
          sequence="1" 
          instruction="Start out on WINTER ST (Going South)" 
          distance="1.2041612436793172"/>
    <segment 
          sequence="2" 
          instruction="Stay STRAIGHT to go onto TOTTEN POND RD (Going East)"
          distance="0.08879983757738225"/>
    <segment 
          sequence="3" 
          instruction="Turn LEFT onto WYMAN ST (Going North)"
          distance="0.24681569656886923"/>
    <segment 
          sequence="4" 
          instruction="Take I-95 N RAMP toward PEABODY" 
          distance="0.23440010735937208"/>
    <segment 
          sequence="5" 
          instruction="Merge onto I-95/RT-128 (Going North)"
          distance="6.002288440990454"/>
    <segment 
          sequence="6" 
          instruction="Continue on I-95/RT-128" 
          distance="0.0"/>
    <segment 
          sequence="7" 
          instruction="Stay STRAIGHT to go onto 32B/32A (Going East)"
          distance="0.15052764594854906"/>
    <segment 
          sequence="8" 
          instruction="Take EXIT 32A toward LOWELL"
          distance="0.032767910543403965"/>
    <segment 
          sequence="9" 
          instruction="Stay STRAIGHT to go onto RAMP (Going East)" 
          distance="0.27877937515534706"/>
    <segment 
          sequence="10" 
          instruction="Turn LEFT onto US-3 (Going Northwest)" 
          distance="20.66104112133381"/>
    <segment 
          sequence="11" 
          instruction="Stay STRAIGHT to go onto FREDERICK E EVERETT 
                            TPKE/US-3 (Going Northwest)"
          distance="0.00588619663828994"/>
    <segment 
          sequence="12" 
          instruction="Take EXIT 1 toward SO NASHUA" 
          distance="0.5504892461007892"/>
    <segment 
          sequence="13" 
          instruction="Turn LEFT onto SPIT BROOK RD (Going West)" 
          distance="0.5032054891878457"/>
    <segment 
          sequence="14" 
          instruction="Turn RIGHT onto ORACLE DR (Going North)" 
          distance="0.3275097635011146"/>
  </route>
</route_response>

Example C-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 C-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 C-4 shows the response generated by the request in Example C-3. (The output is reformatted for readability.)

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

<route_response>
  <route id="8" step_count="13" distance="7261.4423828125" distance_unit="meter" 
    time="441.9170837402344" time_unit="second">
      <route_geometry>
        <LineString>
          <coordinates> 
-122.39381999996483,37.79517999996185 -122.39382,37.79518 -122.39458,37.79598 -122.39469,37.796
-122.39474,37.796 -122.39479,37.79599 -122.39483,37.79591 -122.39483,37.79579 -122.39462,37.79539
-122.39424,37.79488 -122.39338,37.79434 -122.39311,37.79413 -122.39275,37.79384 -122.39258,37.79368
-122.39171,37.79297 -122.39145,37.79273 -122.39127,37.79248 -122.3912,37.79235 -122.39107,37.79208
-122.39098,37.79185 -122.39088,37.79161 -122.39075,37.79138 -122.39048,37.79105 -122.3901,37.79079
-122.38918,37.79001 -122.38877,37.78968 -122.38857,37.78948 -122.38939,37.78882 -122.39024,37.78815
-122.39113,37.78745 -122.39192,37.7868 -122.39284,37.78606 -122.39372,37.78535 -122.39406,37.78507
-122.39511,37.78426 -122.39565,37.78383 -122.39621,37.78337 -122.39728,37.78252 -122.39824,37.78177
-122.39955,37.78075 -122.39963,37.78032 -122.3997,37.78011 -122.39984,37.77991 -122.40071,37.77899
-122.40085,37.77888 -122.40129,37.77855 -122.40182,37.77815 -122.40245,37.77776 -122.40302,37.77737
-122.40375,37.77695 -122.40433,37.77657 -122.40529,37.77592 -122.40581,37.7755 -122.40605,37.77524
-122.4063,37.77493 -122.40656,37.7744 -122.40671,37.7739 -122.40683,37.77312 -122.40671,37.77264
-122.4066,37.77216 -122.40634,37.77151 -122.40594,37.77074 -122.40573,37.77022 -122.4055,37.76958
-122.40547,37.76913 -122.40541,37.76843 -122.40542,37.76791 -122.40547,37.76743 -122.40541,37.76715
-122.40526,37.76579 -122.4051,37.7645 -122.40513,37.76404 -122.40519,37.76356 -122.40544,37.7629 -122.40561,37.76257 -122.40586,37.76218 -122.40619,37.76161 -122.40636,37.7612 -122.40648,37.76063
-122.40642,37.75996 -122.40633,37.75965 -122.4061,37.75918 -122.40574,37.75875 -122.40543,37.75846
-122.4045,37.75778 -122.40402,37.75735 -122.4038,37.75712 -122.40365,37.75688 -122.40344,37.75645
-122.4033,37.75588 -122.40326,37.75537 -122.40316,37.75437 -122.40304,37.75256 -122.40376,37.7502
-122.40384,37.74976 -122.40396,37.74969 -122.40454,37.74947 -122.40468,37.74933 -122.40474,37.74921
-122.40471,37.74902 -122.4045,37.74873 -122.40417,37.74839 -122.404,37.7482 -122.40378,37.74799
-122.40376,37.74781 -122.40428,37.74623 -122.40428,37.74598 -122.40417,37.74557 -122.40419,37.74483
-122.40431,37.74423 -122.40443,37.74396 -122.40468,37.74353 -122.40509,37.74294 -122.40472,37.74274
-122.40512,37.7422 -122.40548260000706,37.74235680000305
          </coordinates>
        </LineString>
      </route_geometry>
      <segment sequence="1" instruction="Start out on THE EMBARCADERO (Going 
        Northwest)" distance="5.246016371529549E-6"/>
      <segment sequence="2" instruction="Stay STRAIGHT to go onto THE
        EMBARCADERO/WORLD TRADE CTR/FERRY PLZ/FERRY
        BLDG (Going Northwest)" distance="111.19815063476562"/>
      <segment sequence="3" instruction="Turn LEFT onto RAMP (Going Southwest)" 
        distance="41.756561279296875"/>
      <segment sequence="4" instruction="Turn LEFT onto THE EMBARCADERO (Going 
        Southeast)" distance="905.924072265625"/>
      <segment sequence="5" instruction="Turn RIGHT onto HARRISON ST (Going 
        Southwest)" distance="1369.1490478515625"/>
      <segment sequence="6" instruction="Take I-80 W RAMP toward SAN JOSE" 
        distance="225.425048828125"/>
      <segment sequence="7" instruction="Turn SLIGHT RIGHT onto I-80/JAMES LICK 
        SKWY (Going Southwest)" distance="1528.181396484375"/>
      <segment sequence="8" instruction="Stay STRAIGHT to go onto 
        US-101/JAMES LICK FWY (Going South)" distance="1765.10498046875"/>
      <segment sequence="9" instruction="Turn SLIGHT RIGHT onto RAMP (Going
        South)" distance="481.18505859375"/>
      <segment sequence="10" instruction="Turn LEFT onto BAY SHORE BLVD (Going
        Southeast)" distance="688.142578125"/>
      <segment sequence="11" instruction="Turn LEFT onto OAKDALE AVE (Going 
        Southeast)" distance="39.44921875"/>
      <segment sequence="12" instruction="Turn RIGHT onto PATTERSON ST (Going
        Southwest)" distance="69.53564453125"/>
      <segment sequence="13" instruction="Turn RIGHT onto FLOWER ST (Going
         Northwest)" distance="36.39051818847656"/>
    </route>
</route_response>

Example C-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 C-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 C-6 shows the response to the request in Example C-5. (The output is reformatted for readability.)

Example C-6 Route Response with Previously Geocoded Locations

<?xml version="1.0" ?> 
<route_response>
  <route 
          id="8" 
          step_count="5" 
          distance="0.5848966065287509" 
          distance_unit="mile"
          time="1.1866167704264323" 
          time_unit="minute">
    <segment 
          sequence="1" 
          instruction="Start out on HUNTINGTON AVE (Going Southeast)" 
          distance="0.005477076104790563" /> 
    <segment 
          sequence="2" 
          instruction="Turn LEFT onto AVENUE OF THE ARTS/HUNTINGTON 
                       AVE/RT-9 (Going Northeast)"
          distance="0.006677015642704102" /> 
    <segment 
          sequence="3" 
          instruction="Turn RIGHT onto PUBLIC ALLEY 405 (Going Southeast)" 
          distance="0.05267257088346108" /> 
    <segment 
          sequence="4" 
          instruction="Turn RIGHT onto ST BOTOLPH ST (Going Southwest)" 
          distance="0.010097520017923165" /> 
    <segment 
          sequence="5" 
          instruction="Turn RIGHT onto MASSACHUSETTS AVE (Going Northwest)"
          distance="0.5099724250650759" /> 
  </route>
</route_response>

C.2.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 element is defined in geocoder.dtd.
   GeometryClasses is defined in gmlgeometry.dtd.
-->
<!ELEMENT route_request (start_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_route_geometry (TRUE|FALSE) #IMPLIED
      return_segment_geometry (TRUE|FALSE) #IMPLIED
      language CDATA #IMPLIED
      distance_unit (KM|MILE|METER) #IMPLIED
      time_unit (HOUR|MINUTE|SECOND) #IMPLIED>
 
<!-- Use this as an alternative to input_location.  Use the
     input_location when you want to represent a location with a  
     street address.  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)>

C.2.2.1 route_request Element

The <route_request> element has the following definition:

<!ELEMENT route_request (start_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, either as an address specification or as a geocoded address.

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

C.2.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_route_geometry (TRUE|FALSE) #IMPLIED
      return_segment_geometry (TRUE|FALSE) #IMPLIED
      language CDATA #IMPLIED
      distance_unit (KM|MILE|METER) #IMPLIED
      time_unit (HOUR|MINUTE|SECOND) #IMPLIED
      pre_geocoded_locations (TRUE|FALSE) #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, the default) or the route with the shortest driving distance (SHORTEST).

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 (the default) returns driving directions; FALSE does not return driving directions.

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

return_segment_geometry is currently ignored.

language is currently ignored.

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_address> element.

C.2.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 C.2.7.1. You can specify the input location using either the <Point> element or the <input_address> element. Example C-1 in Section C.2.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, and you must use the <input_location> element to specify both the start and end locations.

C.2.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 C-5 in Section C.2.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.

C.2.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 segment segment*, (LineString | MultiLineString)?>
<!ATTLIST segment sequence CDATA #REQUIRED
                  instruction CDATA #IMPLIED
                  distance CDATA #IMPLIED>

C.2.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 C.2.5 for requests and Section C.2.6 for responses.

Example C-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 C-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 C-8 shows the response generated by the request in Example C-7. (The output is reformatted for readability.)

Example C-8 Batch Route Response with Specified Addresses

<?xml version="1.0" standalone="yes" ?> 
<batch_route_response 
          id="8">
  <route 
          id="11" 
          step_count="0" 
          distance="9.132561517429938" 
          distance_unit="mile" 
          time="12.4705078125" 
          time_unit="minute" /> 
  <route 
          id="12" 
          step_count="0" 
          distance="17.74747391140558" 
          distance_unit="mile" 
          time="20.413236490885417" 
          time_unit="minute" /> 
  <route 
          id="10" 
          step_count="0" 
          distance="30.28667355371901" 
          distance_unit="mile" 
          time="35.02037760416667" 
          time_unit="minute" /> 
</batch_route_response>

Example C-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 C-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 C-10 shows the response to the request in Example C-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 C-10 Batch Route Response with Previously Geocoded Locations

<?xml version="1.0" standalone="yes" ?> 
<batch_route_response id="8">
  <route 
          id="2" 
          step_count="0" 
          distance="0.5848966065287509" 
          distance_unit="mile" 
          time="1.1866167704264323"
          time_unit="minute" /> 
  <route 
          id="4" 
          step_count="0" 
          distance="41.09054596719071" 
          distance_unit="mile" 
          time="45.4477294921875"
          time_unit="minute" /> 
</batch_route_response>

C.2.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
      return_driving_directions (TRUE | FALSE) #IMPLIED
      return_route_geometry (TRUE|FALSE) #IMPLIED
      language CDATA #IMPLIED
      distance_unit (KM | MILE | METER ) #IMPLIED
      time_unit (HOUR | MINUTE | SECOND) #IMPLIED
      sort_by_distance (TRUE | FALSE) #IMPLIED
      cutoff_distance CDATA #IMPLIED>
          
<!—- Use this as an alternative to input_location.  Use the
     input_location when you want to represent a location with a  
     street address.  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.
-->

C.2.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, either as an address specification or as a geocoded address.

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

C.2.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
      return_driving_directions (TRUE|FALSE) #IMPLIED
      return_route_geometry (TRUE|FALSE) #IMPLIED
      language CDATA #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 C.2.5.2. However, for a batch route request, the return_driving_directions and return_route_geometry attribute values must be FALSE. 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 C.2.6), the route is removed from the response and not shown.

C.2.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>

C.2.7 Geocoding Request and Response DTDs

This section presents the DTDs for requests to geocode an address and for responses to these requests. These DTDs are supported only for use with route requests, and they are not explained in detail.

C.2.7.1 Geocoding Request DTD

The DTD for a request to geocode an address is as follows:

<!-- geocode_request DTD includes the GML Feature 
DTD as an external entity reference. The complete 
URL for the DTD is:
http://www.opengis.org/techno/specs/00-029/gmlfeature.dtd 
 -->
<!ENTITY % GMLFEATUREDTD SYSTEM "gmlfeature.dtd">
%GMLFEATUREDTD;
<!ELEMENT geocode_request (address_list)>
<!ATTLIST geocode_request >
<!ELEMENT address_list (input_location+)>
<!ELEMENT input_location (Point | input_address)>
<!ATTLIST input_location
  id CDATA #IMPLIED
  multimatch_number CDATA "4">
 
<!ELEMENT input_address (us_form1 | us_form2 | gdf_form | gen_form | unformatted)>
<!ATTLIST input_address match_mode CDATA #IMPLIED >
<!ELEMENT gdf_form EMPTY>
<!ATTLIST gdf_form
  name CDATA #IMPLIED
  street CDATA #IMPLIED
  intersecting_street CDATA #IMPLIED
  builtup_area CDATA #IMPLIED
  order8_area CDATA #IMPLIED
  order2_area CDATA #IMPLIED
  order1_area CDATA #IMPLIED
  country CDATA #IMPLIED
  postal_code CDATA #IMPLIED
  postal_addon_code CDATA #IMPLIED>
 
<!ELEMENT gen_form EMPTY>
<!ATTLIST gen_form
  name CDATA #IMPLIED
  street CDATA #IMPLIED
  intersecting_street CDATA #IMPLIED
  sub_area CDATA #IMPLIED
  city CDATA #IMPLIED
  region CDATA #IMPLIED
  country CDATA #IMPLIED
  postal_code CDATA #IMPLIED
  postal_addon_code CDATA #IMPLIED>
 
<!ELEMENT us_form1 EMPTY>
<!ATTLIST us_form1
  name CDATA #IMPLIED
  street CDATA #IMPLIED
  intersecting_street CDATA #IMPLIED
  lastline CDATA #IMPLIED>
 
<!ELEMENT us_form2 EMPTY>
<!ATTLIST us_form2
  name CDATA #IMPLIED
  street CDATA #IMPLIED
  intersecting_street CDATA #IMPLIED
  city CDATA #IMPLIED
  state CDATA #IMPLIED
  zip_code CDATA #IMPLIED>
 
<!ELEMENT unformatted (address_line) >
<!ATTLIST unformatted country CDATA #IMPLIED >
<!ELEMENT address_line EMPTY >
<!ATTLIST value #REQUIRED >

C.2.7.2 Geocoding Response DTD

The DTD for a response generated by a request to geocode an address is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT geocode_response (geocode+)>
 
<!ELEMENT geocode (match*)>
<!ATTLIST geocode id CDATA #REQUIRED
                  match_count CDATA #IMPLIED
 >
 
<!ELEMENT match (output_address)>
<!ATTLIST match sequence CDATA #REQUIRED
                longitude CDATA #REQUIRED
                latitude CDATA #REQUIRED
                match_code CDATA #REQUIRED
                error_message CDATA #IMPLIED >
 
<!ELEMENT output_address EMPTY>
<!ATTLIST output_address 
                name CDATA #IMPLIED
                house_number CDATA #IMPLIED 
                street CDATA #IMPLIED
                builtup_area CDATA #IMPLIED
                order1_area CDATA #IMPLIED
                order8_area CDATA #IMPLIED
                country CDATA #IMPLIED
                postal_code CDATA #IMPLIED
                postal_addon_code CDATA #IMPLIED
                side CDATA #IMPLIED 
                percent CDATA #IMPLIED 
                edge_id CDATA #IMPLIED>

C.3 Data Structures Used by the Routing Engine

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

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.

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

C.3.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 C-1.

Table C-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.)


C.3.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 C-2.

Table C-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 .


C.3.3 PARTITION Table

The PARTITION table is generated by Oracle based on the contents of the EDGE and NODE tables. (If the contents of the EDGE or NODE table, or both tables, change, you call the ROUTER_PARTITION_PKG.PARTITION_ROUTER PL/SQL procedure to partition the data, and then swap the new partition table for the existing partition table. The ROUTER_PARTITION_PKG is created when you install the routing engine.) The PARTITION table contains the columns shown in Table C-3.

Table C-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_BOUNDARY_EDGES

NUMBER

Number of edges in this partition that start in one partition and terminate in a different 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.)


C.3.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 C-4.

Table C-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).