GetFeatureInfo

GetFeatureInfo provides feature information by identifying a point on a map based on its pixel location. The GetFeatureInfo request embeds many of the parameters required in the GetMap request along with parameters specific to querying layers.

In the OGC WMS specification, GetFeatureInfo is optional. The specification leaves the response format open, and there is no standard. ESRI uses stylesheets that are described in the section Output formats.

The following parameters can be appended to the GetFeatureInfo request. See the WMS Specification documentation for detailed descriptions of each parameter. The parameters listed with an asterix (*) are also required in a GetMap request.

Request Parameter	Required/Optional	Description
REQUEST=GetFeatureInfo	R	Request name.
VERSION=version*	R	Request version. Valid values are 1.0.0, 1.1.0, or 1.1.1.
SRS=EPSG:id_code*	R	Spatial Reference System (SRS) identifier the map is returned in. Identifiers correspond to coordinate system ID codes found in the ArcXML Programmer’s Reference Guide.
BBOX=minx,miny,maxx,maxy*	R	Bounding box corners (lower left, upper right). Values must be in the units of the specified SRS.
WIDTH=output_width*	R	Width in pixels of resulting map image.
HEIGHT=output_height*	R	Height in pixels of resulting map image.
QUERY_LAYERS=layer_list	R	Comma-separated list of one or more map layers to be queried. Values in the list correspond to the layer <name> values in the Capabilities file. This name corresponds to the layer id in ArcXML.
X=pixel_column	R	X coordinate in pixels of feature measured from upper left corner of the map.
Y=pixel_row	R	Y coordinate in pixels of feature measured from upper left corner of the map.
INFO_FORMAT=output_format	O	Return format of feature information. The default value is application/vnd.ogc.wms_xml. Other options are text/xml, text/html, and text/plain.
FEATURE_COUNT=number	O	Number of features per layer allowed. The default is 1.
EXCEPTIONS=exception_format	O	The format in which exceptions are reported. The default and only supported value is application/vnd.ogc.se_xml.
SERVICENAME=service_name (vendor specific)	O	By default, the capabilities of the default WMS service is queried. If you want to use a non-default service, the service name must be included in the URL.

Examples

Example 1: Using the minimum amount of parameters

This example shows the minimum number of parameters needed to make a successful GetFeatureInfo request. This example uses the default WMS service, which is the service name you selected in the WMS Connector Administrator. For more information about the Administrator page, see Using the WMS Connector Administrator.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetFeatureInfo&SRS=EPSG:4326&BBOX=-117,38,-90,49&WIDTH=600&HEIGHT=400&QUERY_LAYERS=States&X=200&Y=150&

where

• <hostname> is the URL domain name for your site such as www.esri.com or a fully qualified machine name.
• <deploy_name> is the name you assigned to the Web application when you deployed the WMS Connector. The recommended deployment name is "wmsconnector".
• http://<hostname>/<deploy_name>/com.esri.wms.Esrimap? is the full URL to access the WMS Connector on an ArcIMS site.
• VERSION=1.1.1 is the WMS request version.
• REQUEST=GetFeatureInfo is the request name.
• SRS=EPSG:4326 is the spatial reference value. This example uses geographic WGS 1984.
• BBOX=-124,21,-66,49 is the bounding box in SRS coordinates of the map. In this example, the coordinates are in decimal degrees.
• WIDTH=600&HEIGHT=400 are the width and height of the image in pixels.
• QUERY_LAYERS=States is the list of layers for retrieving information. You do not need to request all layers, but each layer name that you do request must be valid.
• X=200&Y=150 is the selection location in pixels measured from the upper left corner of the image.

Example 2: Specifying a nondefault WMS service

In this next example, a non-default WMS service is specified.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap?VERSION=1.1.1&REQUEST=GetFeatureInfo&SRS=EPSG:4326&BBOX=-117,38,-90,49&WIDTH=600&HEIGHT=400&QUERY_LAYERS=States&X=200&Y=150&SERVICENAME=myService&

where

• SERVICENAME=myService is the service you are requesting. The service name is case sensitive.

A second way to specify a non-default WMS service does not use the SERVICENAME parameter.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap/myService?VERSION=1.1.1&REQUEST=GetFeatureInfo&SRS=EPSG:4326&BBOX=-117,38,-90,49&WIDTH=600&HEIGHT=400&QUERY_LAYERS=States&X=200&Y=150&

where

• /myService is the service you are requesting. The name is case sensitive and must be placed before the question mark (?) in the URL.

Example 3: Using optional parameters

In the following example, optional parameters are specified. This URL should be all on one line.

http://<hostname>/<deploy_name>/com.esri.wms.Esrimap?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetFeatureInfo&SRS=EPSG:4326&BBOX=-117,38,-90,49&WIDTH=600&HEIGHT=400&QUERY_LAYERS=States&X=200&Y=150&SERVICENAME=myService& INFO_FORMAT=text/html&EXCEPTIONS=application/vnd.ogc.se_xml&FEATURE_COUNT=5&

where

• INFO_FORMAT=text/html determines the output format.
• EXCEPTIONS=application/vnd.ogc.se_xml is the exceptions output format, in this case XML.
• FEATURE_COUNT=5 determines the maximum number of features per layer that are returned in any response.

Note: Hard returns added to URLs for readability

Output formats

The WMS specification does not specify an output format for a response. ESRI has provided four XSL stylesheets located in the expanded WAR file's WEB-INF directory.

• Application/vnd.ogc.wms_xml
• Text/xml
• Text/html
• Text/plain

The location of the expanded WAR file directory varies depending on the servlet engine you are using. However, the structure of the expanded WAR file is the always the same.

<Application Name>
      |__WAR
         |__WEB_INF
            |__classes
               |__wms
                  |__stylesheets
                     |__wms_featureinfo.xsl
                     |__wms_featureinfo_html.xsl
                     |__wms_featureinfo_plain.xsl
                     |__wms_featureinfo_xml.xsl

where

• <Application Name> is the name of your application when you deployed the WAR file. The recommended name is wmsconnector.

Each of the stylesheets provides a different output format.

Application/vnd.ogc.wms_xml output format

The application/vnd.ogc.wms_xml format is an XML format, and the referenced XSL stylesheet is wms_featureinfo.xsl. A typical response looks like the following. The fields are listed alphabetically inside a FeatureInfoResponse tag. A separate FIELDS tag exists for each returned feature for each layer.

<?xml version="1.0" encoding="UTF-8"?> <FeatureInfoResponse> <FIELDS FEMALES="226581" MALES="227007" POP1999="482025" STATE_NAME="Wyoming" _ID_="6" _SHAPE_="[Geometry]" _LAYERID_="0"/> </FeatureInfoResponse>

Text/xml output format

The text/xml format is the same XML format as vnd.ogc.wms_xml. However, this format displays correctly in Internet Explorer and Netscape. The referenced XSL stylesheet is wsm_featureinfo_xml.xsl.

Text/html output format

The text/html format displays the data in an HTML table.

FEMALES	MALES	POP1999	STATE_NAME	_ID_	_SHAPE_	_LAYERID_
226581	227007	482025	Wyoming	6	[Geometry]	0

The look and feel can be changed by modifying the XSL stylesheet wms_featureinfo_html.xsl. Some common changes are to modify the table color or format.

1. Open wms_featureinfo_html.xsl in a text or XML editor.
2. To change the colors, search for the following
   
   • th bgcolor="#006699" for the table header background color. Change "#006699" to the new color of your choice.
   • font color="#FFFFFF" for the font color. Change "#FFFFFF" to the new color of your choice.
   • td bgcolor="#99CCFF" for the table row background color. Change "#99CCFF" to the new color of your choice.
3. To change the HTML table format, search for <table. You can add additional HTML table attributes as desired.

Text/plain output format

The text/plain format returns data in a text string. Each field is delimited by a space by default. If a field value contains a space and is surrounded by double quotes (").

"FEMALES" "MALES" "POP1999" "STATE_NAME" "_ID_" " _SHAPE_" "_LAYERID_"
"226581" "227007" "482025" "Wyoming" "6" "[Geometry]" "0"

The attribute delimiter can be changed in the XSL stylesheet named wms_featureinfo_plain.xsl.

1. Open wms_featureinfo_plain.xsl in a text or XML editor.
2. Search for the following string:

   <xsl:value-of select="x"/>

3. The value immediately following this string is the delimiter. Change this to the delimiter of your choice.

Errors

The GetFeatureInfo response returns an XML structure containing error information if the WMS service detected an error.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <ServiceExceptionReport version="1.1.1"> <ServiceException> Invalid query_layers value </ServiceException> </ServiceExceptionReport>

You will always receive an error if the HTTP request is improperly formatted or a required parameter is missing. Common error messages are:

Problem	Error message
REQUEST missing	Missing mandatory REQUEST parameter. Possibilities are {capabilities|GetCapabilities|map|GetMap|feature_info|GetFeatureInfo}
VERSION missing	Missing VERSION | WMTVER parameter
SRS missing	Missing SRS parameter or value
BBOX missing or one of the values is missing	Invalid BBOX value
Invalid BBOX value	Invalid BBOX NumberFormatException: For input string: "<value>"
WIDTH missing	Invalid WIDTH NumberFormatException : null
Invalid WIDTH value	Invalid WIDTH NumberFormatException : For input string: <value>
HEIGHT missing	Invalid HEIGHT NumberFormatException : null
Invalid HEIGHT value	Invalid HEIGHT NumberFormatException : For input string: <value>
QUERY_LAYERS missing	Missing QUERY_LAYERS parameter or value
Invalid query layer name	GetFeatureInfo Error: [ERR0706] Layer with ID {id} not found.
X (pixel_column) missing	Invalid 'X' value, NumberFormatException : null
Invalid X (pixel_column) value	Invalid 'X' value, NumberFormatException : For input string: <value>
Y (pixel_column) missing	Invalid 'Y' value, NumberFormatException : null
Invalid Y (pixel_column) value	Invalid 'Y' value, NumberFormatException : For input string: <value>
Requested service name is not valid	Access to the specified service <service_name> is not available

In some cases, an ArcIMS error message is returned. More information on these error messages is available in the Error messages portion of this help system.

Problem	ArcIMS Error message
Requested service is not available. The ArcIMS Service may be stopped or busy.	Error sending FeatureInfo response. Exception in FeatureInfo reply Error: [ERR0134] Requested service is not available.