Using the Geocoding Service (XML API)

12.7 Using the Geocoding Service (XML API)

In addition to the SQL API, Oracle Spatial also provides an XML API for a geocoding service that enables you to geocode addresses.

A Java geocoder application engine performs international address standardization, geocoding, and POI matching, by querying geocoder data stored in the Oracle database. The support for unparsed addresses adds flexibility and convenience to customer applications.

This geocoding service is implemented as a Java 2 Enterprise Edition (J2EE) Web application that you can deploy in a WebLogic Server environment.

Figure 12-1 shows the basic flow of action with the geocoding service: a client locates a remote geocoding service instance, sends a geocoding request, and processes the response returned by the geocoding service instance.

Figure 12-1 Basic Flow of Action with the Spatial Geocoding Service

Description of "Figure 12-1 Basic Flow of Action with the Spatial Geocoding Service"

As shown in Figure 12-1:

The client sends an XML geocoding request, containing one or more input addresses to be geocoded, to the geocoding service using the HTTP protocol.
The geocoding service parses the input request and looks up the input address in the database.
The geocoding service sends the geocoded result in XML format to the client using the HTTP protocol.

After you load the geocoder schema into the database, you must configure the J2EE geocoder before it can be used, as explained in Deploying and Configuring the J2EE Geocoder

Parent topic: Geocoding Address Data

12.7.1 Deploying and Configuring the J2EE Geocoder

The J2EE geocoder processes geocoding requests and generates responses. To enable this geocoding service, a geocoder.ear.zip file must be deployed using Oracle WebLogic Server. To deploy and configure the geocoding service, follow these steps.

Deploy the geocoder using Oracle WebLogic Server:
1. Unzip the geocoder.ear.zip file found in your $ORACLE_HOME/md/jlib directory into a suitable directory. Your resulting directory structure should be: $geocoder.ear/web.war/....
2. Log on to the WebLogic Server console (for example, http://<hostname>:7001/console); and from Deployments install the geocoder.ear file, accepting the Name geocoder for the deployment and choosing the Location option Make the deployment accessible from the following location.
Launch the geocoder welcome page in a web browser using the URL http://<hostname>:<port>/geocoder . On the welcome page, select the Administration link and enter the administrator (weblogic) user name and password.

Note:

If you are not using the default WebLogic administrator user name (weblogic) , you will need to edit the weblogic.xml file located in the $geocoder.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>.

If the welcome page was not displayed, ensure that the newly deployed geocoding service was successfully started. (It is assumed that you are running WebLogic Server 12.1 or later with an Oracle Database 12.2 or later geocoder.ear.zip file.)
Modify the geocoder configuration file (geocodercfg.xml). Uncomment at least one <geocoder> element, and change the <database> element attributes of that <geocoder> element to reflect the configuration of your database. For information about this file, see Configuring the geocodercfg.xml File.
Save the changes to the file, and restart the geocoder.
Test the database connection by going to the welcome page at URL http://<hostname>:<port>/geocoder and running the XML geocoding request page. (This demo requires geocoder data for the United States.)

Examples are available to demonstrate various capabilities of the geocoding service. Reviewing the examples at URL http://<hostname>:<port>/geocoder/gcxmlreq_exp_af.html is a good way to learn the XML API, which is described in Geocoding Request XML Schema Definition and Example.

Configuring the geocodercfg.xml File

Parent topic: Using the Geocoding Service (XML API)

12.7.1.1 Configuring the geocodercfg.xml File

You will need to edit the <database> element in the geocodercfg.xml file to specify the database and schema where the geocoding data is loaded. The geocodercfg.xml file is accessed through the Administrator link on the geocoder welcome page, and is stored in the $geocoder.ear/web.war/WEB-INF/config directory of the geocoder application

In the geocodercfg.xml file, each <geocoder> element defines the geocoder for the database in which the geocoder schema resides. The <database> element defines the database connection for the geocoder. In Oracle Database 12.2, the database connection is defined by providing the JNDI name (container_ds) of a predefined container data source. See the WebLogic Server documentation, Configuring and Managing WebLogic JDBC: Creating a JDBC Data Source for information about defining data sources.

Example 12-6 illustrates how a <database> element can be defined. The definition uses the JNDI name of a predefined container data source.

Example 12-6 <database> Element Definition

<database container_ds="jdbc/gc_usa"
          load_db_parser_profiles="true" />

The attributes of the <database> element are as follows

container_ds specifies the JNDI name for a predefined data source.
load_db_parser_profiles specifies whether to load the address parser profiles from the specified database connection. It is recommended that you set this parameter to true when parser profile tables are provided with the geocoder data. If the value is true, the address parser-profiles are loaded from the geocoder schema; otherwise, the parser profiles are loaded from the application at ../applications/geocoder/web/WEB-INF/parser_profiles/<country-name>.ppr (for example, usa.ppr).

Parent topic: Deploying and Configuring the J2EE Geocoder

12.7.2 Geocoding Request XML Schema Definition and Example

For a geocoding request (HTTP GET or POST method), it is assumed the request has a parameter named xml_request whose value is a string containing the XML document for the request. The input XML document describes the input addresses that need to be geocoded. One XML request can contain one or more input addresses. Several internationalized address formats are available for describing the input addresses. (The input XML API also supports reverse geocoding, that is, a longitude/latitude point to a street address.)

The XML schema definition (XSD) for a geocoding request is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Schema for an XML geocoding request that takes one or more input_locations and supports reverse geocoding using the input_location's attributes -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xsd:complexType name="address_lineType">
    <xsd:attribute name="value" type="xsd:string" use="required"/>
  </xsd:complexType>
  <xsd:complexType name="address_listType">
    <xsd:sequence>
      <xsd:element name="input_location" type="input_locationType"
         maxOccurs="unbounded"/>
    </xsd:sequence>
  </xsd:complexType>
  <xsd:complexType name="gdf_formType">
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="street" type="xsd:string"/>
    <xsd:attribute name="intersecting_street" type="xsd:string"/>
    <xsd:attribute name="builtup_area" type="xsd:string"/>
    <xsd:attribute name="order8_area" type="xsd:string"/>
    <xsd:attribute name="order2_area" type="xsd:string"/>
    <xsd:attribute name="order1_area" type="xsd:string"/>
    <xsd:attribute name="country" type="xsd:string"/>
    <xsd:attribute name="postal_code" type="xsd:string"/>
    <xsd:attribute name="postal_addon_code" type="xsd:string"/>
  </xsd:complexType>
  <xsd:complexType name="gen_formType">
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="street" type="xsd:string"/>
    <xsd:attribute name="intersecting_street" type="xsd:string"/>
    <xsd:attribute name="sub_area" type="xsd:string"/>
    <xsd:attribute name="city" type="xsd:string"/>
    <xsd:attribute name="region" type="xsd:string"/>
    <xsd:attribute name="country" type="xsd:string"/>
    <xsd:attribute name="postal_code" type="xsd:string"/>
    <xsd:attribute name="postal_addon_code" type="xsd:string"/>
  </xsd:complexType>
  <xsd:element name="geocode_request">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="address_list" type="address_listType"/>
      </xsd:sequence>
      <xsd:attribute name="vendor" type="xsd:string"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:complexType name="input_addressType">
    <xsd:choice>
      <xsd:element name="us_form1" type="us_form1Type"/>
      <xsd:element name="us_form2" type="us_form2Type"/>
      <xsd:element name="gdf_form" type="gdf_formType"/>
      <xsd:element name="gen_form" type="gen_formType"/>
      <xsd:element name="unformatted" type="unformattedType"/>
    </xsd:choice>
    <xsd:attribute name="match_mode" default="relax_postal_code">
      <xsd:simpleType>
        <xsd:restriction base="xsd:NMTOKEN">
          <xsd:enumeration value="exact"/>
          <xsd:enumeration value="relax_street_type"/>
          <xsd:enumeration value="relax_poi_name"/>
          <xsd:enumeration value="relax_house_number"/>
          <xsd:enumeration value="relax_base_name"/>
          <xsd:enumeration value="relax_postal_code"/>
          <xsd:enumeration value="relax_builtup_area"/>
          <xsd:enumeration value="relax_all"/>
          <xsd:enumeration value="DEFAULT"/>
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:attribute>
  </xsd:complexType>
  <xsd:complexType name="input_locationType">
    <xsd:sequence>
      <xsd:element name="input_address" type="input_addressType"
         minOccurs="0"/>
    </xsd:sequence>
    <xsd:attribute name="id" type="xsd:string"/>
    <xsd:attribute name="country" type="xsd:string"/>
    <xsd:attribute name="longitude" type="xsd:string"/>
    <xsd:attribute name="latitude" type="xsd:string"/>
    <xsd:attribute name="x" type="xsd:string"/>
    <xsd:attribute name="y" type="xsd:string"/>
    <xsd:attribute name="srid" type="xsd:string"/>
    <xsd:attribute name="multimatch_number" type="xsd:string" default="1000"/>
  </xsd:complexType>
  <xsd:complexType name="unformattedType">
    <xsd:sequence>
      <xsd:element name="address_line" type="address_lineType"
         maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="country" type="xsd:string"/>
  </xsd:complexType>
  <xsd:complexType name="us_form1Type">
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="street" type="xsd:string"/>
    <xsd:attribute name="intersecting_street" type="xsd:string"/>
    <xsd:attribute name="lastline" type="xsd:string"/>
  </xsd:complexType>
  <xsd:complexType name="us_form2Type">
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="street" type="xsd:string"/>
    <xsd:attribute name="intersecting_street" type="xsd:string"/>
    <xsd:attribute name="city" type="xsd:string"/>
    <xsd:attribute name="state" type="xsd:string"/>
    <xsd:attribute name="zip_code" type="xsd:string"/>
  </xsd:complexType>
</xsd:schema>

Example 12-7 is a request to geocode several three addresses (representing two different actual physical addresses), using different address formats and an unformatted address.

Example 12-7 Geocoding Request (XML API)

<?xml version="1.0" encoding="UTF-8"?>
<geocode_request xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../geocode_request.xsd">
  <address_list>
    <input_location id="1">
      <input_address>
        <us_form2 name="Oracle" street="500 Oracle Parkway" city="Redwood City"
           state="CA" zip_code="94021"/>
      </input_address>
    </input_location>
    <input_location id="2">
      <input_address>
 <gdf_form street="1 Oracle Drive" builtup_area="Nashua" order1_area="NH"
        postal_code="03062" country="US"/>
      </input_address>
    </input_location>
    <input_location id="3">
      <input_address>
<gen_form street="1 Oracle Drive" city="Nashua" region="NH" postal_code="03062" country="US"/>
      </input_address>
    </input_location>
    <input_location id="4">
      <input_address>
        <unformatted country="UNITED STATES">
          <address_line value="Oracle NEDC"/>
          <address_line value="1 Oracle drive "/>
          <address_line value="Nashua "/>
          <address_line value="NH"/>
        </unformatted>
      </input_address>
    </input_location>
  </address_list>
</geocode_request>

Parent topic: Using the Geocoding Service (XML API)

12.7.3 Geocoding Response XML Schema Definition and Example

A geocoding response contains one or more standardized addresses including longitude/latitude points, the matching code, and possibly multiple match and no match indication and an error message.

The XML schema definition (XSD) for a geocoding response is as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Schema for an XML geocoding response -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xsd:complexType name="geocodeType">
    <xsd:sequence>
      <xsd:element name="match" type="matchType" minOccurs="0"
         maxOccurs="unbounded"/>
    </xsd:sequence>
    <xsd:attribute name="id" type="xsd:string" use="required"/>
    <xsd:attribute name="match_count" type="xsd:string"/>
  </xsd:complexType>
  <xsd:element name="geocode_response">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="geocode" type="geocodeType" maxOccurs="unbounded"/>
      </xsd:sequence>
    </xsd:complexType>
  </xsd:element>
  <xsd:complexType name="matchType">
    <xsd:sequence>
      <xsd:element name="output_address" type="output_addressType"/>
    </xsd:sequence>
    <xsd:attribute name="sequence" type="xsd:string" use="required"/>
    <xsd:attribute name="longitude" type="xsd:string" use="required"/>
    <xsd:attribute name="latitude" type="xsd:string" use="required"/>
    <xsd:attribute name="match_code" use="required">
      <xsd:simpleType>
        <xsd:restriction base="xsd:NMTOKEN">
          <xsd:enumeration value="0"/>
          <xsd:enumeration value="1"/>
          <xsd:enumeration value="2"/>
          <xsd:enumeration value="3"/>
          <xsd:enumeration value="4"/>
          <xsd:enumeration value="10"/>
          <xsd:enumeration value="11"/>
          <xsd:enumeration value="12"/>
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:attribute>
    <xsd:attribute name="error_message" type="xsd:string"/>
  </xsd:complexType>
  <xsd:complexType name="output_addressType">
    <xsd:attribute name="name" type="xsd:string"/>
    <xsd:attribute name="house_number" type="xsd:string"/>
    <xsd:attribute name="street" type="xsd:string"/>
    <xsd:attribute name="builtup_area" type="xsd:string"/>
    <xsd:attribute name="order1_area" type="xsd:string"/>
    <xsd:attribute name="order8_area" type="xsd:string"/>
    <xsd:attribute name="country" type="xsd:string"/>
    <xsd:attribute name="postal_code" type="xsd:string"/>
    <xsd:attribute name="postal_addon_code" type="xsd:string"/>
    <xsd:attribute name="side" type="xsd:string"/>
    <xsd:attribute name="percent" type="xsd:string"/>
    <xsd:attribute name="edge_id" type="xsd:string"/>
  </xsd:complexType>
</xsd:schema>

Example 12-8 is the response to the request in Example 12-7 in Geocoding Request XML Schema Definition and Example.

Example 12-8 Geocoding Response (XML API)

<?xml version="1.0" encoding="UTF-8"?>
<geocode_response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="../geocode_response.xsd">
 <geocode id="1" match_count="1">
    <match sequence="0" 
         longitude="-122.26193971893862" latitude="37.53195483966782"
         match_code="10" error_message="????#ENUT?B281C??">
      <output_address name="" house_number="500" street="ORACLE PKY"
           builtup_area="REDWOOD CITY" order1_area="CA" order8_area="" 
           country="US" postal_code="94065" postal_addon_code="" side="L" 
           percent="0.33166666666666667" edge_id="28503563"/>
    </match>
 </geocode>
 <geocode id="2" match_count="1">
   <match sequence="0" 
        longitude="-71.45937299307225" latitude="42.70784494226865"
        match_code="1" error_message="????#ENUT?B281CP?">
      <output_address name="" house_number="1" street="ORACLE DR"
            builtup_area="NASHUA" order1_area="NH" order8_area="" 
            country="US" postal_code="03062" postal_addon_code="" side="L" 
            percent="0.01" edge_id="22325991"/>
   </match>
 </geocode>
 <geocode id="3" match_count="1">
   <match sequence="0" 
         longitude="-71.45937299307225" latitude="42.70784494226865"
         match_code="1" error_message="????#ENUT?B281CP?">
      <output_address name="" house_number="1" street="ORACLE DR"
            builtup_area="NASHUA" order1_area="NH" order8_area="" 
            country="US" postal_code="03062" postal_addon_code="" side="L" 
            percent="0.01" edge_id="22325991"/>
   </match>
 </geocode>
 <geocode id="4" match_count="1">
   <match sequence="0" 
         longitude="-71.45937299307225" latitude="42.70784494226865"
         match_code="1" error_message="????#ENUT?B281CP?">
     <output_address name="" house_number="1" street="ORACLE DR"
           builtup_area="NASHUA" order1_area="NH" order8_area="" 
           country="US" postal_code="03062" postal_addon_code="" side="L" 
           percent="0.01" edge_id="22325991"/>
   </match>
 </geocode>
</geocode_response>

Parent topic: Using the Geocoding Service (XML API)