In addition to the SQL API, Oracle Spatial and Graph 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 11-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 11-1 Basic Flow of Action with the Spatial Geocoding Service
As shown in Figure 11-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
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.
You will need to edit the <database>
element in the default geocodercfg.xml
file that is included with Spatial and Graph, to specify the database and schema where the geocoding data is loaded.
In this 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 11g or later, there are two ways to define a database connection: by providing the JDBC database connection parameters, or by providing the JNDI name (container_ds
) of a predefined container data source.
Example 11-6 illustrates two different ways in which a <database>
element can be defined. The first definition specifies a JDBC connection; the second definition uses the JNDI name of a predefined container data source.
Example 11-6 <database> Element Definitions
<database name="gcdatabase" host="gisserver.example.com" port="1521" sid="orcl" mode="thin" user="geocoder_us" password="geocoder_us" load_db_parser_profiles="true" /> <database container_ds="jdbc/gc_europe" load_db_parser_profiles="true" />
The attributes of the <database>
element are as follows
name
is a descriptive name for the database connection; it is not used to connect to the database.
host
, port
, and sid
identify the database.
mode
identifies the type of JDBC driver to use for the connection.
user
and password
are the user name and password for the database user under whose schema the geocoding data is stored.
load_db_parser_profiles
specifies whether to load the address parser profiles from the specified database connection. If 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). Before Oracle 11g, parser profiles were loaded from the application only. This parameter should be set to true
.
container_ds
specifies the JNDI name for a predefined data source.
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 11-7 is a request to geocode several three addresses (representing two different actual physical addresses), using different address formats and an unformatted address.
Example 11-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>
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: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 11-8 is the response to the request in Example 11-7 in Geocoding Request XML Schema Definition and Example.
Example 11-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>