Oracle Maps Cloud | Geocoder Concepts

A Client application communicates with the Geocoder server over the Internet in the following manner:
1. The Client sends an XML geocoding request containing an input address to the Geocoder server via HTTP.
2. The Geocoder server parses the input request and invokes the Geocoder to lookup the input address in the database.
3. The Geocoder server then sends the geocoded result in XML to the Client via HTTP.

XML API

This section explains how to submit a request to the Geocoder server in XML. It also describes the XML Schema Definition (XSD) for the Geocoder requests (input) and responses (output).

Geocoding Request XSD and Example XML Request

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. The request XML document describes the input addresses that are to be geocoded. An XML request may contain one or more input addresses, and multiple internationalized address representations are available for describing the input addresses. The request XML API also supports reverse geocoding, i.e. converting latitude/longitude points into street addresses.

Request XSD:

<?xml version="1.0" encoding="UTF-8"?>

<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="house_number" 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>

XML Request Example:

<?xml version="1.0" encoding="UTF-8" ?>

<geocode_request>

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

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

Geocoding Response XSD and Example XML Response

The XML response contains standardized addresses and longitude/latitude points. It also contains multiple-match and no-match indicators: a match vector, and a match code.

Response XSD:

<?xml version="1.0" encoding="UTF-8"?>

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

XML Response Example:

<?xml version="1.0" encoding="UTF-8" ?>

<geocode_response>

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

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

</match>

</geocode>

</match>

</geocode>

</geocode_response>

Address Representation

The Geocoder recognizes 5 input-address representation formats:

1. us_form1

US address format; addresses consist of the follow fields:

name	Place name
intersecting_street	Intersecting street names
street	Street address (house number, street name, etc.)
lastline	City, state, zip code

2. us_form2

US address format; addresses consist of the following fields:

name	Place name
street	Street address (house number, street name, etc.)
intersecting_street	Intersecting street names
city	City name
state	State name
zip_code	Zip code

3. gen_form

General (international) address format; addresses consist of the following fields:

name	Place name
street	Street address
intersecting_street	Intersecting street names
sub_area	Name of a sub-area within a city; big European cities may be divided into multiple smaller districts
city	City name
region	Region(state/province) name
country	ISO 2-digit country code or country name
postal_code	Postal code
postal_addon_code	Postal add-on code

4. gdf_form

GDF standard address format; addresses consist of the following fields:

name Place name

street Street address

intersecting_street Intersecting street names

builtup_area GDF built-up-area name, equivalent to a US city

order8_area GDF order8-area name, equivalent to a US county

order2_area GDF order2-area name

order1_area GDF order1-area name, equivalent to a US state

country ISO 2-digit country code or country name

postal_code Postal code

postal_addon_code Postal add-on code

5. unformatted

Addresses are organized by postal address lines, not by meaningful fields. Address lines may contain information, such as, name/title of a person, company name, street address, city, and state/province -- some of which may not be necessary for geocoding. An unformatted address for a particular country should be in the correct postal-address format for that country.

Demo/Examples

Match Modes

The Geocoder performs matching based on a strictness parameter the user inputs with the address. The strictness attribute, "match_mode" in a geocoding XML request tells the Geocoder which matching algorithm to use.

EXACT All fields provided must match exactly

RELAX_STREET_TYPE Street type can be different from the one entered

RELAX_POI_NAME POI name does not have to match exactly

RELAX_HOUSE_NUMBER House number and street type do not have to match

RELAX_BASE_NAME Base name, house number and street type do not have to match

RELAX_POSTAL_CODE Postal code (if provided), base name, house number and street type do not have to match

RELAX_BUILTUP_AREA Search for the address outside the specified city, but within the same county; it includes RELAX_POSTAL_CODE

RELAX_ALL Same as RELAX_BUILTUP_AREA

DEFAULT Same as RELAX_POSTAL_CODE

The Geocoder always attempts to find an exact match or the closest matches as determined by the string-edit distance (i.e. the number of character changes required to match the input), even when the relax_all criterion is specified.
The Geocoder can return multiple matches, up to 4 records, for an input address -- ordered by the closeness of the match.

Demo/Examples

Geocoding Result Interpretation

There are two ways to learn about the result of a geocoding response:

1. Match Code

Note: If there was no match, the match_code attribute is set to 0.

12	The region is matched, but the postal code and city name are not matched
11	The postal code is matched, but the city name is not matched
10	The city name is matched, but the postal code is not matched
4	The postal code and city name are matched, but the street address is not matched
3	The city name, postal code and street base name are matched, but the house number is not matched
2	The city name, postal code, street base name and house number are matched, but the street type, suffix or prefix is not matched
1	An exact match: city name, postal code, street base name, street type/suffix/prefix and house number are matched

2. Match Vector

The match_vector attribute contains a string that indicates which input address fields matched the data stored in the geocoder tables. It provides a more accurate and detailed description than the error_message attribute, which it supersedes. The value of the match_vector string is set to ????????????????? before the geocoding operation begins. It is then modified to reflect which address attributes were matched during the geocoding operation. The first table, lists the positions in the string and the address attribute corresponding to each position. The numeric value to which the position in the string is set may vary from 0-4. A description of these values is given in the second table.

Position Attribute

1-2 Reserved for future use

3 Address point

4 POI name

5 House or building number

6 Street prefix

7 Street base name

8 Street suffix

9 Street type

10 Secondary unit

11 Built-up area/city

12-13 Reserved for future use

14 Order1/region/state

15 Country

16 Postal code

17 Postal add-on code

Value	Description
0	The input attribute is not null and is matched with a non-null value
1	The input attribute is null and is matched with a null value
2	The input attribute is not null and is replaced by a different non-null value
3	The input attribute is not null and is replaced by a null value
4	The input attribute is null and is replaced by a non-null value

A question mark indicates and unused field position. If a user does not supply a field, for example, a postal code, and the field is subsequently filled by the Geocoder, the field value is set to 4.

Demo/Examples

Batch Geocoding Requests

The Geocoder supports batch geocoding. It is more efficient than multiple single requests, since it saves network round trips.
An address of a batch geocoding request can be in any format and match mode. Addresses are identified by the "id" attribute of the "location_id" tag. The "id" attribute of a geocoding response matches the "id" attribute of the input address.

Demo/Examples

Legal Notices | End-User Terms | Feedback