Summary of Geocoding Elements

Introduction

Geocoding is the process of identifying the coordinates of a location given its address. ArcXML uses geocode elements in four situations:
  1. To specify a layer's geocoding properties in a map configuration file.
  2. To request a point based on an address.
  3. To receive a response about geocoding information in the map configuration file.
  4. To receive a response with the location of an address.
The following table lists the nine ArcXML geocode elements and where each element is used:

Geocode Element Used in:
ADDRESS GET_GEOCODE request.
FEATURECOORDSYS GET_GEOCODE request.
GCCOUNT GEOCODE response.
GCFIELD Map configuration file.
GCINPUT SERVICEINFO response.
GCSTYLE Map configuration file and SERVICEINFO response.
GCTAG GET_GEOCODE request.
GEOCODE GEOCODE response.
GET_GEOCODE GET_GEOCODE request.

Geocode Elements Used in a Map Configuration File

When creating a geocoded layer in a map configuration file, the information for geocoding is included in the EXTENSION element. The extension identifies the style of geocoding that should be used. There are two elements used inside EXTENSION:

GCSTYLE is used to list the address style. GCFIELD is used to describe the different input parameters from the database needed for that style. Below is an example of using GCSTYLE and GCFIELD in an EXTENSION.

Using GCSYTLE and GCFIELD in an EXTENSION:
<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <CONFIG>
    <ENVIRONMENT>
      <LOCALE country="US" language="en" variant="" />
      <UIFONT color="0,0,0" name="Arial" size="12" style="regular" />
    </ENVIRONMENT>
    <MAP>
      <PROPERTIES>
       <ENVELOPE minx="-71.077092" miny="42.357962" maxx="-71.034511" maxy="42.385263" name="Initial_Extent" />
       <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <WORKSPACES>
       <SHAPEWORKSPACE name="shp_ws-64" directory="<path to data>" />
      </WORKSPACES>
      <LAYER type="featureclass" name="Streets" visible="true" id="4">
       <DATASET name="bosstreets" type="line" workspace="shp_ws-64" />
       <SIMPLERENDERER>
         <SIMPLELINESYMBOL type="solid" width="2" color="255,0,0" />
       </SIMPLERENDERER>
       <EXTENSION type="Geocode">
         <GCSTYLE name="USAddressZ">
<!--reqd--> <GCFIELD id="FromLeft" name="L_F_ADD" />
<!--reqd--> <GCFIELD id="FromRight" name="R_F_ADD" />
<!--reqd--> <GCFIELD id="ToLeft" name="L_T_ADD" />
<!--reqd--> <GCFIELD id="ToRight" name="R_T_ADD" />
            <GCFIELD id="PreDir" name="PREFIX" />
            <GCFIELD id="PreType" name="PRE_TYPE" />
<!--reqd--> <GCFIELD id="StreetName" name="NAME" />
            <GCFIELD id="StreetType" name="TYPE" />
            <GCFIELD id="SufDir" name="SUFFIX" />
<!--reqd--> <GCFIELD id="LeftZone" name="ZIPL" />
<!--reqd--> <GCFIELD id="RightZone" name="ZIPR" />
         </GCSTYLE>
       </EXTENSION>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

ArcIMS has 10 standard address styles, most of which are valid only in the United States. See the Notes and Examples sections for GCSTYLE and Using ArcIMS, the "Setting Geocode Properties" section of Chapter 3, for more information on address styles. ArcIMS also supports the implementation of custom address styles. See Using Custom Address Styles for information on customizing address styles for use in another country or for special cases in the United States.

Geocode Elements Used in GET_GEOCODE Requests

All geocode requests must be routed to the Geocode Server. This routing information is contained in the URL that is sent to the ArcIMS site such as in the following example (all one line):
http://myComputer.domain.com/servlet/com.esri.esrimap.Esrimap?ClientVersion=3.1
        &ServiceName=myservice
        &CustomService=Geocode
        &Form=True&Encode=True

Requests to geocode an address are made using GET_GEOCODE. The geocode elements used in this request are: The address to geocode is added to GCTAG in the request. The id and value in GCTAG vary depending on which address style is used. In the example below, the "STREET" id is "380 New York Street" and the "Zone" id is "92373". No data is added to "CrossStreet".

A GET_GEOCODE request:
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_GEOCODE maxcandidates="25" minscore="60">
      <LAYER id="4" />
      <ADDRESS>
        <GCTAG id="STREET" value="380 New York Street" />
        <GCTAG id="Zone" value="92373" />
        <GCTAG id="CrossStreet" value="" />
      </ADDRESS>
    </GET_GEOCODE>
    </REQUEST>
</ARCXML>

FEATURECOORDSYS is needed if the x- and y-cooordinates for the geocoded point are in a different coordinate system than the MapService. For example, if the MapService is in geographic coordinates, but the client is in Robinson, then FEATURECOORDSYS should be used to request the coordinates in Robinson. The next example requests the points in Robinson (id="53030"). For more information on using FEATURECOORDSYS, see Using Projection Elements.

A GET_GEOCODE request with FEATURECOORDSYS:
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_GEOCODE maxcandidates="25" minscore="60">
      <LAYER id="4" />
      <FEATURECOORDSYS id="53030">
      <ADDRESS>
        <GCTAG id="STREET" value="380 New York Street" />
        <GCTAG id="Zone" value="92373" />
        <GCTAG id="CrossStreet" value="" />
      </ADDRES>
    </GET_GEOCODE>
    </REQUEST>
</ARCXML>

Geocode Elements Used in a GEOCODE Response

A GEOCODE response is returned based on information in the GET_GEOCODE request. Geocode elements included in the response are: For each candidate returned in the response, address information and its location are included. The total number of returned features is included in GCCOUNT. An example GEOCODE response is:

A GEOCODE response:
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
   <RESPONSE>
     <GEOCODE>
       <FEATURE featureid="1">
         <FIELD type="4" name="SCORE" size="5" precision="0">
           <FIELDVALUE valuestring="100" />
         </FIELD>
         <FIELD type="12" name="ADDRESSFOUND" size="21" precision="0">
           <FIELDVALUE valuestring="380 NEW YORK ST 92373" />
         </FIELD>
         <FIELD type="-98" name="SHAPEFIELD">
           <FIELDVALUE>
         <POINT x="-117.19496116" y="34.05777355" />
           </FIELDVALUE>
         </FIELD>
       </FEATURE>
       <GCCOUNT count="1" />
     </GEOCODE>
   </RESPONSE>
</ARCXML>

Geocode Elements Used in a SERVICEINFO Response

If a MapService includes a geocodable layer, the extension information is included in a SERVICEINFO response. To get this information, set the attribute extensions to true in the GET_SERVICE_INFO request. An example request is:

GET_SERVICE_INFO request:
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_SERVICE_INFO extensions="true" renderer="false" fields="false" envelope="false" />
  </REQUEST>
</ARCXML>

The request can be sent directly to the Image Server or can be routed to the Geocode Server. The information returned is different depending on which server is used. If the request is sent to the Image Server, the extension information is returned but includes only GCSTYLE.

SERVICEINFO response with MapService EXTENSION information and GCSYTLE:
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <SERVICEINFO>
      <ENVIRONMENT>
        <LOCALE language="en" country="US" />
        <UIFONT name="Arial" color="0,0,0" size="12" style="regular" />
        <SEPARATORS cs=" " ts=";"/>
        <IMAGELIMIT pixelcount="2250000" />
      </ENVIRONMENT>
      <PROPERTIES>
        <ENVELOPE minx="-71.0718204242754" miny="42.368904975182" maxx="-71.0475995680561" maxy="42.3869647980717" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
      </PROPERTIES>
      <LAYERINFO type="featureclass" visible="true" name="bosstreets" id="1" maxscale="0.0000470313026173583">
        <FCLASS type="line"></FCLASS>
        <EXTENSION type="Geocode" >
          <GCSTYLE name="USAddressZ" />
        </EXTENSION>
      </LAYERINFO>
    </SERVICEINFO>
  </RESPONSE>
</ARCXML>

If the GET_SERVICE_INFO request is routed to the Geocode Server, the SERVICEINFO response includes the following geocode elements: A sample response is:

SERVICEINFO response rerouted to the Geocode Server:
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <SERVICEINFO>
      <ENVIRONMENT>
        <LOCALE language="en" country="US" />
        <UIFONT name="Arial" color="0,0,0" size="12" style="regular" />
         <SEPARATORS cs=" " ts=";"/>
      </ENVIRONMENT>
      <LAYERINFO name="streets" id="1" >
         <EXTENSION type="geocode">
           <GCSTYLE name="USAddressZ" >
            <GCINPUT id="STREET" type="text" label="Street" width="10" description="street number, street name and type" />
            <GCINPUT id="ZONE" type="text" label="Zone" width="5" description="zone information" />
            <GCINPUT id="CROSSSTREET" type="text" label="Cross street" width="10" description="cross street name and type" />
           </GCSTYLE>
         </EXTENSION>
      </LAYERINFO>
    </SERVICEINFO>
  </RESPONSE>
</ARCXML>

The id attribute values for GCINPUT are the same values that need to be included in GCTAG in the GET_GEOCODE request.