Using GET_FEATURES and FEATURES

Introduction

GET_FEATURES is a versatile request that can be used to access geometric information about selected items, the attribute results of a query, or both. The information is returned in a FEATURES response.

GET_FEATURES requests can be made on Image and Feature Services. The following map configuration file is used for the GET_FEATURES examples in this document. The file consists of five layers from the ESRIDATA data set. The following table summarizes the layer names, shapefile names, and layer ID numbers.

Layer NameShapefile Name Layer ID
OceanWORLD300
CountriesCNTRY941
StatesSTATES2
ProvincesPROVINCE3
CitiesCITIES4



Map configuration file used with the GET_FEATURES requests that follow
<?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 dynamicfeature="true" >
      <PROPERTIES>
        <ENVELOPE minx="-180" miny="-90" maxx="180" maxy="90" name="Initial_Extent" />
        <MAPUNITS units="decimal_degrees" />
        <FILTERCOORDSYS id="4326" />
        <FEATURECOORDSYS id="4326"/>
      </PROPERTIES>
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-0" directory="C:\ESRIDATA\WORLD" />
        <SHAPEWORKSPACE name="shp_ws-2" directory="C:\ESRIDATA\USA" />
        <SHAPEWORKSPACE name="shp_ws-3" directory="C:\ESRIDATA\CANADA" />
      </WORKSPACES>
      <LAYER type="featureclass" name="Ocean" visible="true" id="0">
        <DATASET name="WORLD30" type="polygon" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="0,153,255" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Countries" visible="true" id="1">
        <DATASET name="CNTRY94" type="polygon" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="255,255,153"/>
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="States" visible="true" id="2">
        <DATASET name="STATES" type="polygon" workspace="shp_ws-2" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="255,0,0" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Provinces" visible="true" id="3">
        <DATASET name="province" type="polygon" workspace="shp_ws-3" />
        <SIMPLERENDERER>
          <SIMPLEPOLYGONSYMBOL filltype="solid" fillcolor="0,153,0" />
        </SIMPLERENDERER>
      </LAYER>
      <LAYER type="featureclass" name="Cities" visible="true" id="4">
        <DATASET name="CITIES" type="point" workspace="shp_ws-0" />
        <SIMPLERENDERER>
          <SIMPLEMARKERSYMBOL color="102,0,102" width="8.0" />
        </SIMPLERENDERER>
      </LAYER>
    </MAP>
  </CONFIG>
</ARCXML>

GET_FEATURES can query only one layer of an ArcIMS service at a time. The request must include either the SPATIALQUERY or QUERY element. The query can be made on attributes, a spatial filter, or a combination of the two. SPATIALQUERY is recommended for all queries since it can handle both attribute and spatial queries.

The following example is a typical GET_FEATURES request. The LAYER has been identified by its ID, which must match the layer ID in the map configuration file. In this example, id="4" refers to the Cities layer. The SPATIALQUERY includes both an attribute query and a spatial filter. The attribute query is for cities with more than 10 million people. The spatial query limits the extent to an area that covers North America.

GET_FEATURES request with LAYER and SPATIALQUERY
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="25" beginrecord="0" outputmode="xml" geometry="false" envelope="true" globalenvelope="true">
      <LAYER id="4" />
      <SPATIALQUERY subfields="NAME POPULATION #SHAPE#" where="POPULATION > 10000000" >
        <SPATIALFILTER relation="area_intersection">
          <ENVELOPE minx="-129" miny="16" maxx="-50" maxy="62"/>
        </SPATIALFILTER>
      </SPATIALQUERY>
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

The information returned in the FEATURES response varies depending on the attributes selected in GET_FEATURES. Each of the attributes is discussed in more detail later in this document.

The following example is the response to the above request. Two cities, Mexico City and New York City, meet the criteria set forth in the SPATIALQUERY. The response includes the location of each city using ENVELOPE. The requested subfields NAME, POPULATION, and #SHAPE# are also included. The response also contains the total number of features returned in FEATURECOUNT and a global extent that encompasses both cities in the last ENVELOPE listed.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>  
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <ENVELOPE minx="-99.127571105957" miny="19.4270458221436" maxx="-99.127571105957" maxy="19.4270458221436"/>
        <FIELDS NAME="Mexico City" POPULATION="14100000" #SHAPE#="[Geometry]" />
      </FEATURE>
      <FEATURE>
        <ENVELOPE minx="-74.0999984741211" miny="40.75" maxx="-74.0999984741211" maxy="40.75"/>
        <FIELDS NAME="New York" POPULATION="16472000" #SHAPE#="[Geometry]" />
      </FEATURE>
      <FEATURECOUNT count="2" hasmore="false" />
      <ENVELOPE minx="-99.127571105957" miny="19.4270458221436" maxx="-74.0999984741211" maxy="40.75"/>
    </FEATURES>
  </RESPONSE>
</ARCXML>

Accessing an ArcIMS Service using GET_FEATURES

Based on attribute settings in a GET_FEATURES request, the FEATURES response returns data in a feature stream or in ArcXML format. Requests to Feature Services are sent to the Feature Server and use the feature streaming format. The stream is a compressed binary format that can be interpreted by only the ArcIMS Java Viewers or ArcExplorer-Java Edition. The binary stream that is returned includes both feature and attribute data.

GET_FEATURES requests to Image and ArcIMS Image Services are limited to data in ArcXML format. When querying an Image Service, two requests must be made to get both a map and attribute data. Requests for a map use GET_IMAGE. Requests for attributes use GET_FEATURES. In order to send a GET_FEATURES request to and Image Service, the request must be "rerouted". The routing is done in the URL when the request is sent. An example URL is (all one line):

http://mycomputer.domain.com/servlet/com.esri.esrimap.Esrimap
    &ServiceName=MyService
    &CustomService=Query
    &Form=True&Encode=True

The table below summarizes the differences when using GET_FEATURES on Feature and Image Services:

  Feature Services Image Services
GET_FEATURES request uses: Feature Streaming ArcXML
FEATURES response uses: Feature Streaming ArcXML
GET_FEATURES request for attribute data sent to: Feature Server Query Server
Request to draw map sent to: Feature Server using GET_FEATURES Image Server using GET_IMAGE

GET_FEATURES has a series of attributes that are used to format the FEATURES response. The formatting attributes are outputmode, compact, geometry, skipfeatures, envelope, attributes, checkesc, and globalenvelope. Other attributes are used to keep track of the number of features in the request and response: beginrecord, featurelimit, count, and hasmore. These attributes are discussed in detail below.

In the following examples and explanations, all requests and responses are in ArcXML format. The requests are made to the map configuration file in the Introduction section, which is assumed to be an Image Service.

Outputmode

The outputmode attribute defines whether the data is streamed to the client or sent to the client in ArcXML format.

Outputmode can have one of three values: If outputmode is binary, then the request is sent to the Feature Server and the response are in a compressed binary stream. This is the default.

If outputmode="xml", then all features are returned in a short ArcXML format inside the FIELDS element of the FEATURES response.

In the next example, the request is made on the States layer (id="2"). The SPATIALQUERY asks for the subfields STATE_NAME and SUB_REGION for the State of Washington.

GET_FEATURES request when outputmode="xml"
<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES outputmode="xml">
      <LAYER id="2" />
      <SPATIALQUERY subfields="state_name sub_region"
where="STATE_NAME='Washington'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

The response returns the requested information on Washington. The attributes are returned on one line inside the FIELDS element. The attribute names are the same as the field names in the database.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <FIELDS STATE_NAME="Washington" SUB_REGION="Pacific" />
      </FEATURE>
      <FEATURECOUNT count="1" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

The "xml" outputmode can be used only when no XML parser is used since the attribute names in FIELD are always changing. When using an XML parser, outputmode should be set to "newxml", which returns data in a valid XML format. If outputmode="newxml", then all fields are returned using the FIELD element. The next request asks for the same information on Washington as the previous request.

GET_FEATURES request when outputmode="newxml"
<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES outputmode="newxml">
      <LAYER id="2" />
      <SPATIALQUERY subfields="state_name sub_region" where="STATE_NAME='Washington'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

The response returns the same information on Washington but each attribute is included inside a separate FIELD element. With this format, the attribute names are standardized in FIELD and do not change.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <FIELDS>
          <FIELD name="STATE_NAME" value="Washington" />
          <FIELD name="SUB_REGION" value="Pacific" />
        </FIELDS>

      </FEATURE>
      <FEATURECOUNT count="1" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

Geometry and Compact

The attribute geometry is used to determine whether feature geometry is returned. The attribute compact is a toggle that can be used to return the geometry in a long or short format in the FEATURES response. By default, the geometry is returned in a longer format using POINT. Note that geometry is returned only if "#SHAPE#" or "#ALL#" is included in subfields in the SPATIALQUERY.

In the next request, geometry is set to "true", and compact is set to "false". The "#SHAPE#" field has been added to the list of subfields in SPATIALQUERY.

GET_FEATURES request when outputmode="xml", geometry="true", and compact="false"
<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES outputmode="xml" geometry="true" compact="false">
      <LAYER id="2" />
      <SPATIALQUERY subfields="#SHAPE# state_name sub_region"
where="STATE_NAME='Washington'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, the geometry for Washington is returned in a longer format. Each point in the polygon is recorded inside the POINT element.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>  
<ARCXML version="1.1">
<RESPONSE>
  <FEATURES>
    <FEATURE>
      <FIELDS STATE_NAME="Washington" SUB_REGION="Pacific" #SHAPE#="[Geometry]" />
      <POLYGON>
        <RING>
          <POINT x="-122.400749" y="48.2253952" />
          <POINT x="-122.461585" y="48.2285423" />
          <POINT x="-122.453155" y="48.1286735" />
          .  .  .  .  .
          <POINT x="-122.400749" y="48.2253952" />

        </RING>
      </POLYGON>
    </FEATURE>
    <FEATURECOUNT count="1" hasmore="false" />
  </FEATURES>
</RESPONSE>
</ARCXML>

When compact="true", the response uses COORDS to return the geometry data in a compact format. In the next request, geometry and compact are set to "true".

GET_FEATURES request when outputmode="xml", geometry="true", and compact="true"
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES outputmode="xml" geometry="true" compact="true">
      <LAYER id="2" />
      <SPATIALQUERY subfields="#SHAPE# state_name sub_region"
where="STATE_NAME='Washington'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, the coordinates are all grouped together inside the COORDS element. Note that this response uses the default separators between the coordinates and coordinate pairs, which are a space and semicolon, respectively. These separators can be changed by using SEPARATORS in the map configuration file or request.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <FIELDS STATE_NAME="Washington" SUB_REGION="Pacific" #SHAPE#="[Geometry]" />
        <POLYGON>
          <RING>
            <COORDS>-122.400749 48.2253952;-122.461585
48.2285423;-122.453155 48.1286735; . . . . .;-122.400749 48.2253952;-122.461585 48.2285423</COORDS>

          </RING>
        </POLYGON>
      </FEATURE>
      <FEATURECOUNT count="1" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

Beginrecord, Featurelimit, Count, Hasmore

The attributes beginrecord and featurelimit are used together in GET_FEATURES to limit the number of features returned in the FEATURES response. If too many features are returned, the processing time in the client may become unacceptable.

Featurelimit is used to set the maximum number of features to return. Beginrecord is used to start the retrieval at a specified record. For example, if a maximum of seven features should be returned, featurelimit is set to "7". For the first retrieval, beginrecord starts at "1" (the default). The following example uses featurelimit and beginrecord.

GET_FEATURES request when featurelimit="7" and beginrecord="1"
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="7" beginrecord="1" outputmode="xml" geometry="false">
      <LAYER id="2" />
      <SPATIALQUERY subfields="#SHAPE# state_name sub_region"
where="SUB_REGION='Mtn'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

The attributes count and hasmore in FEATURECOUNT in the FEATURES response contain information on the number of features returned and whether more features are available to extract. To determine whether more features are available to extract, hasmore is set to "true" for more records or "false" for no more records. In this example, the number of features returned in count is "7", and hasmore is set to "true".

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        . . . First 6 Records Returned . . .
      </FEATURE>
      <FEATURE>
        <FIELDS STATE_NAME="Arizona" SUB_REGION="Mtn" #SHAPE#="[Geometry]" />  
      </FEATURE>
      <FEATURECOUNT count="7" hasmore="true" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

If more features are still available, another GET_FEATURES request should be sent, this time with beginrecord set to "8". The developer is responsible for handling additional requests programmatically.

GET_FEATURES request when featurelimit="7" and beginrecord="8"
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="7" beginrecord="8" outputmode="xml" geometry="false">
      <LAYER id="2" />
      <SPATIALQUERY subfields="#SHAPE# state_name sub_region"
where="SUB_REGION='Mtn'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, count is set to "1", and hasmore is set to "false", indicating that no more records need to be extracted.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>  
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <FIELDS STATE_NAME="New Mexico" SUB_REGION="Mtn" #SHAPE#="[Geometry]" />
      </FEATURE>
      <FEATURECOUNT count="1" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

Skipfeatures

When the attribute skipfeatures is used, no features are returned; only the feature count is returned. Skipfeatures is valid only if outputmode is "xml" or "newxml". In the following request, a query is made on the Cities layer (id="4") for cities with a population greater than 10 million.

GET_FEATURES request using skipfeatures
<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES skipfeatures="true" outputmode="newxml">
      <LAYER id="4" />
      <SPATIALQUERY subfields="#ALL#" where="POPULATION &gt; 10000000" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

The response includes only the FEATURECOUNT. In this example, 11 cities have a population greater than 10 million.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURECOUNT count="11" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

To get the total number of features in a layer, a SPATIALQUERY can be specified with an empty where clause. Note that even when skipfeatures is set to "true", the query is executed and features are actually processed before they are counted.

GET_FEATURES request using skipfeatures and empty where clause
<?xml version="1.0" encoding="UTF-8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES skipfeatures="true" outputmode="newxml" >
      <LAYER id="4" />
      <SPATIALQUERY subfields="#ALL#" where="" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, the total number of features for the layer is included.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURECOUNT count="606" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

Envelope, Attributes, and Checkesc

The attribute envelope is used to request the bounding envelope of each returned feature.

The attribute attributes is used to determine whether the attribute data should be returned. If only geometry is needed, then attributes can be set to "false".

The attribute checkesc is used if the returned data should include escaped characters for ampersand, single quote, double quote, less than, and greater than. For example, if the value for SUB_REGION in the States layer were "P&NW", then:

In the next request, attributes, envelope, and checkesc are set to "true".

GET_FEATURES request when attributes="true", envelope="true", and checkesc="true"
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES outputmode="xml" geometry="false" attributes="true" envelope="true" checkesc="true">
      <LAYER id="2" />
      <SPATIALQUERY subfields="#SHAPE# state_name sub_region" where="STATE_NAME='Washington'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, ENVELOPE contains the bounding extent of Washington. FIELDS contains the attribute information. The value for SUB_REGION has been escaped to "P&amp;NW".

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <ENVELOPE minx="-124.731422" miny="45.5432510" maxx="-116.918151" maxy="49.0000038"/>
        <FIELDS STATE_NAME="Washington" SUB_REGION="P&amp;NW" #SHAPE#="[Geometry]" />
      </FEATURE>
      <FEATURECOUNT count="1" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>  

Globalenvelope

The attribute globalenvelope is used to request the bounding envelope of all features returned in the response. Since the number of features returned depends on beginrecord and featurelimit, only the actual records extracted based on featurelimit are included in the overall envelope. Note that in order for the global envelope to be returned, subfields in the SPATIALQUERY must include either "#SHAPE#" or "#ALL#".

In the next example, attributes is set to "false" and envelope and globalenvelope are set to "true". A query is made on the States layer for states in the Pacific region.

GET_FEATURES request when attributes="false", envelope="true", and gloabalenvelope="true"
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES outputmode="xml" geometry="false" attributes="false" envelope="true" globalenvelope="true">
      <LAYER id="2" />
      <SPATIALQUERY subfields="#SHAPE#" where="SUB_REGION='Pacific'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, an ENVELOPE is included for each FEATURE but no attributes are included for the FEATURE. At the end of the response, the overall bounding ENVELOPE is included.

FEATURES response
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <ENVELOPE minx="-124.731422424316" miny="45.5432510375977" maxx="-116.918151855469" maxy="49.0000038146973"/>
      </FEATURE>
      <FEATURE>
        <ENVELOPE minx="-124.558395385742" miny="41.9877891540527" maxx="-116.469444274902" maxy="46.2362594604492"/>
      </FEATURE>
      <FEATURE>
        <ENVELOPE minx="-124.391471862793" miny="32.5357246398926" maxx="-114.124450683594" maxy="42.0023460388184"/>
      </FEATURE>
      <FEATURE>
        <ENVELOPE minx="-160.245178222656" miny="18.9247817993164" maxx="-154.793869018555" maxy="22.2324924468994"/>
      </FEATURE>
      <FEATURE>
        <ENVELOPE minx="-178.215026855469" miny="51.5844345092773" maxx="-129.990539550781" maxy="71.4066467285156"/>
      </FEATURE>
      <FEATURECOUNT count="5" hasmore="false" />
      <ENVELOPE minx="-178.215026855469" miny="18.9247817993164" maxx="-114.124450683594" maxy="71.4066467285156"/>
    </FEATURES>
  </RESPONSE>
</ARCXML>

Transforming Geometry

Both FILTERCOORDSYS and FEATURECOORDSYS can be used with GET_FEATURES to transform data. Data that can be transformed includes the ENVELOPE and coordinates listed under either POINT or COORDS.

FILTERCOORDSYS is used to specify the coordinate system of the requesting client. FEATURECOORDSYS is used to specify the coordinate system to which the service should be transformed. For more information on these elements, see Using Projection Elements.

In this first example, the client is in Robinson, so FILTERCOORDSYS id="54030". In the request, the coordinates in the SPATIALFILTER are in Robinson. FEATURECOORDSYS also has an id="54030", which means that the requested data should be returned in Robinson. The request is made on the Cities layer (id="4").

The service, by default, is in geographic coordinates. This means that the ArcIMS Spatial Server receives the request and first transforms the Robinson coordinates into geographic coordinates. After the extraction has been made, the coordinates are transformed back into Robinson coordinates. Depending on the complexity of the data and the amount of features extracted, the processing time can be considerable when data transformations are involved.

Using FILTERCOORDSYS and FEATURECOORDSYS in a GET_FEATURES request
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="25" beginrecord="0" outputmode="xml" geometry="true" envelope="true" compact="true">
      <LAYER id="4" />
      <SPATIALQUERY subfields="#ALL#" where="POPULATION > 10000000" >
        <FILTERCOORDSYS id="54030" />
        <FEATURECOORDSYS id="54030" />

        <SPATIALFILTER relation="area_intersection">
          <ENVELOPE minx="-11395772" miny="930558" maxx="-3878142" maxy="6419621"/>
        </SPATIALFILTER>
      </SPATIALQUERY>
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, the coordinates inside the ENVELOPE and COORDS elements are returned in Robinson.

FEATURES response with FILTERCOORDSYS and FEATURECOORDSYS set to Robinson ("54030")
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <ENVELOPE minx="-9197766.55659269" miny="2075483.92733491" maxx="-9197766.55659269" maxy="2075483.92733491"/>
        <FIELDS NAME="Mexico City" COUNTRY="Mexico" POPULATION="14100000" CAPITAL="Y" #SHAPE#="[Geometry]" #ID#="221" />
        <MULTIPOINT>
          <COORDS>-9197766.55659269 2075483.92733491</COORDS>
        </MULTIPOINT>
      </FEATURE>
      <FEATURE>
        <ENVELOPE minx="-6419931.44911452" miny="4351163.61842219" maxx="-6419931.44911452" maxy="4351163.61842219"/>
        <FIELDS NAME="New York" COUNTRY="US" POPULATION="16472000" CAPITAL="N" #SHAPE#="[Geometry]" #ID#="549" />
        <MULTIPOINT>
          <COORDS>-6419931.44911452 4351163.61842219</COORDS>
        </MULTIPOINT>
      </FEATURE>
      <FEATURECOUNT count="2" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

In the next example, the client is once again in Robinson, and FILTERCOORDSYS id="54030". However, the data to be returned is requested in geographic coordinates. Therefore, FEATURECOORDSYS is set to id="4326". This request should process faster than the previous one. When the ArcIMS Spatial Server receives the request, the Robinson coordinates must still be transformed to geographic coordinates. However, since the data is requested back in geographic coordinates, no further transformation is needed on the data.

Using FILTERCOORDSYS in Robinson ("54030") and FEATURECOORDSYS in geographic coordinates ("4326") in a GET_FEATURES request
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="25" beginrecord="0" outputmode="xml" geometry="true" envelope="true" compact="true">
      <LAYER id="4" />
      <SPATIALQUERY subfields="#ALL#" where="POPULATION > 10000000" >
        <FILTERCOORDSYS id="54030" />
        <FEATURECOORDSYS id="4326" />

        <SPATIALFILTER relation="area_intersection">
          <ENVELOPE minx="-11395772" miny="930558" maxx="-3878142" maxy="6419621"/>
        </SPATIALFILTER>
      </SPATIALQUERY>
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

In the response, the coordinate data in the ENVELOPE and COORDS elements is in geographic coordinates.

FEATURES response with FILTERCOORDSYS set to Robinson (54030) and FEATURECOORDSYS set to geographic coordinates (4326)
<?xml version="1.0" encoding="UTF8"?>
<ARCXML version="1.1">
  <RESPONSE>
    <FEATURES>
      <FEATURE>
        <ENVELOPE minx="-99.127571105957" miny="19.4270458221436" maxx="-99.127571105957" maxy="19.4270458221436"/>
        <FIELDS NAME="Mexico City" COUNTRY="Mexico" POPULATION="14100000" CAPITAL="Y" #SHAPE#="[Geometry]" #ID#="221" />
        <MULTIPOINT>
           <COORDS>-99.127571105957 19.4270458221436</COORDS>
        </MULTIPOINT>
      </FEATURE>
      <FEATURE>
        <ENVELOPE minx="-74.0999984741211" miny="40.75" maxx="-74.0999984741211" maxy="40.75"/>
        <FIELDS NAME="New York" COUNTRY="US" POPULATION="16472000" CAPITAL="N" #SHAPE#="[Geometry]" #ID#="549" />
        <MULTIPOINT>
          <COORDS>-74.0999984741211 40.75</COORDS>
        </MULTIPOINT>
      </FEATURE>
      <FEATURECOUNT count="2" hasmore="false" />
    </FEATURES>
  </RESPONSE>
</ARCXML>

Querying dynamic layers

Starting with ArcIMS 9.1, dynamic layers can be queried in a GET_FEATURES request. "Dynamic" means adding a layer to the request that is not listed in the map configuration file. This functionality is valid with Image Services only and not Feature Services.

Before queries can be made on dynamic layers, the dynamic query functionality must be enabled in the map configuration file. The attribute dynamicfeature must be included in the MAP element and set to "true".

<MAP dynamic="true" dynamicfeature="true" >

In the following request, instead of using an existing layer in the map configuration file, a new layer is added.

Querying a dynamic layer
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="5" beginrecord="0" outputmode="xml" geometry="false" envelope="true" compact="true">
      <LAYER id="40" type="featureclass" >
        <DATASET name="country" type="polygon" workspace="shp_ws-0" />
      </LAYER>

      <SPATIALQUERY subfields="#ALL#" where="POP_CNTRY &gt; 100000000" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

Adding a dynamic layer requires adding more information to LAYER and including DATASET. LAYER requires two attributes: id and type. The id value should be a unique ID not already used in the map configuration file. The type value should always be set to "featureclass". The DATASET workspace must reference an existing workspace defined in the map configuration file or in the request. Whenever possible, workspaces should be referenced in the map configuration file rather than the request. This provides a level of security since WORKSPACES requires a path name or ArcSDE reference to the data.

In the next request, subfields are referenced in the query.

Using subfields in a dynamic query
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="5" beginrecord="0" outputmode="xml" geometry="false" envelope="true" compact="true">
      <LAYER id="40" type="featureclass" >
        <DATASET name="country" type="polygon" workspace="shp_ws-0" />
      </LAYER>
      <SPATIALQUERY subfields="CNTRY_NAME POP_CNTRY" where="POP_CNTRY &gt; 100000000" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

Since the layer is dynamic, no GET_SERVICE_INFO request can be made against the layer to return a list of field names. Thus, the developer is responsible for knowing ahead of time what the field names are. To get around this problem, leave subfields out of the request, or use "#ALL#" for the value.

In some cases, you may need to add WORKSPACES in the request. In a GET_FEATURES request, only shapefile and ArcSDE workspaces are valid. The following example reference shapefiles.

Adding WORKSPACES to the request
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="5" beginrecord="0" outputmode="xml" geometry="false" envelope="true" compact="true">
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-5" directory="<path to EUROPE ESRIDATA>" />
      </WORKSPACES>
      <LAYER type="featureclass" id="40"> <!-- cities in Europe directory -->
        <DATASET name="cities" type="point" workspace="shp_ws-5" />
      </LAYER>
      <SPATIALQUERY subfields="#ALL#" where="CNTRY_NAME = 'Finland'" />
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

Using a buffer layer and target layer in a GET_FEATURES request is common among ArcIMS users. The buffer layer, target layer, or both can be dynamic. The following example uses a dynamic target layer. The syntax is the same as for other dynamic layers. TARGETLAYER requires the id and type attributes, and DATASET must also be included.

Using a target layer
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="25" beginrecord="1" outputmode="xml" geometry="false" envelope="false" checkesc="true">       <LAYER id="4" />
<!--from the map configuration file-->
      <SPATIALQUERY>
        <BUFFER distance="500" bufferunits="miles">
          <TARGETLAYER id="40" type="featureclass" >
            <DATASET name="country" type="polygon" workspace="shp_ws-0" />
          </TARGETLAYER>

        </BUFFER>
        <SPATIALFILTER relation="area_intersection" >
          <ENVELOPE minx="94.261119081779" miny="42.8694404591104" maxx="100.459110473457" maxy="51.1334289813486" />
        </SPATIALFILTER>
      </SPATIALQUERY>
    </GET_FEATURES>
  </REQUEST>
</ARCXML>

When WORKSPACES is included, separate workspaces can be used for the buffer and target layers.

Including multiple workspaces in a request
<?xml version="1.0" encoding="UTF-8" ?>
<ARCXML version="1.1">
  <REQUEST>
    <GET_FEATURES featurelimit="25" beginrecord="1" outputmode="xml" geometry="false" envelope="false" checkesc="true">
      <WORKSPACES>
        <SHAPEWORKSPACE name="shp_ws-5" directory="<path to EUROPE ESRIDATA>" />
        <SHAPEWORKSPACE name="shp_ws-6" directory="<path to WORLD ESRIDATA>" />
      </WORKSPACES>

      <LAYER type="featureclass" id="40"> <!-- cities in Europe directory -->
        <DATASET name="cities" type="point" workspace="shp_ws-5" />
      </LAYER>
      <SPATIALQUERY>
        <BUFFER distance="800" bufferunits="miles">
          <TARGETLAYER id="41" type="featureclass" >
            <DATASET name="country" type="polygon" workspace="shp_ws-6" />
          </TARGETLAYER>
        </BUFFER>
        <SPATIALFILTER relation="area_intersection" >
          <ENVELOPE minx="24.239598278335" miny="61.1549497847919" maxx="26.492109038737" maxy="63.3859397417503" />
        </SPATIALFILTER>
      </SPATIALQUERY>
    </GET_FEATURES>
  </REQUEST>
</ARCXML>