to the National Atlas Home page
About | Fact Sheets | Contact Us | Partners | Products | Site Map | FAQ | Help | Follow us on Twitter 
Part of Project LogoAgricultureBiologyBoundariesClimateEnvironmentGeologyGovernmentHistoryMappingPeopleTransportationWater
to the Interactive Map MakerMap LayersPrintable MapsWall MapsDynamic MapsArticlesMapping Professionals

Technical Information About the National Atlas Web Map Service


Web Map Service Introduction

 

These instructions are for Web map services (WMS) consumers who want to connect to nationalatlas.gov™ using Open Geospatial Consortium (OGC) protocols for interoperability and access. Anyone can connect to the National Atlas of the United States® by supplying valid OGC parameter values to our Web services uniform resource locator (URL).

An Introduction to National Atlas Web Map Services is also available.

Accessing the Capabilities File
The National Atlas WMS currently contains over 2,400 individual layers. A single capabilities file for all layers is available, but because it is quite a large file, we have also grouped the layers into broad categories that correspond to the chapters of the National Atlas. Use the online addresses in Table 1 to access the capabilities file for the categories of interest to you.

Category URL Size
1 Million-Scale Map Layers http://webservices.nationalatlas.gov/wms/1million?SERVICE=WMS&REQUEST=GetCapabilities 41 KB 
Agriculture http://webservices.nationalatlas.gov/wms/agriculture?SERVICE=WMS&REQUEST=GetCapabilities 33 KB 
Biology http://webservices.nationalatlas.gov/wms/biology?SERVICE=WMS&REQUEST=GetCapabilities 1.55 MB 
Boundaries http://webservices.nationalatlas.gov/wms/boundaries?SERVICE=WMS&REQUEST=GetCapabilities 16 KB 
Climate http://webservices.nationalatlas.gov/wms/climate?SERVICE=WMS&REQUEST=GetCapabilities 100 KB 
Environment http://webservices.nationalatlas.gov/wms/environment?SERVICE=WMS&REQUEST=GetCapabilities 24 KB 
Geology http://webservices.nationalatlas.gov/wms/geology?SERVICE=WMS&REQUEST=GetCapabilities 51 KB 
Government http://webservices.nationalatlas.gov/wms/government?SERVICE=WMS&REQUEST=GetCapabilities 48 KB 
History http://webservices.nationalatlas.gov/wms/history?SERVICE=WMS&REQUEST=GetCapabilities 12 KB 
Map Reference http://webservices.nationalatlas.gov/wms/map_reference?SERVICE=WMS&REQUEST=GetCapabilities 12 KB 
People http://webservices.nationalatlas.gov/wms/people?SERVICE=WMS&REQUEST=GetCapabilities 456 KB 
Transportation http://webservices.nationalatlas.gov/wms/transportation?SERVICE=WMS&REQUEST=GetCapabilities 22 KB 
Water http://webservices.nationalatlas.gov/wms/water?SERVICE=WMS&REQUEST=GetCapabilities 144 KB 
All Layers http://webservices.nationalatlas.gov/wms?SERVICE=WMS&REQUEST=GetCapabilities 5.46 MB 

Table 1: Summary of National Atlas Capabilities Files

The above URLs will default to WMS version 1.3.0. You can change the WMS version by appending an optional version parameter with the desired WMS version. For example, to specify WMS version 1.1.1, append "&VERSION=1.1.1" to the URLs in Table 1. Details of the GetCapabilities Request parameters are included in Table 2.

 Parameter Description Required/
Optional
 Valid Values  Default Value
SERVICE=WMS The name of the service. In this case, Web Map Service. Required WMS  
REQUEST=GetCapabilities The type of request. Required GetCapabilities  
VERSION=version The version of the requested service. Optional 1.3.0, 1.1.1, 1.1.0, 1.0.7, 1.0.0 1.3.0

Table 2: GetCapabilities Request Parameters

Note for Esri Users
If you use ArcGIS 9.3.x, be sure to specify WMS version 1.1.1 or lower.

Building a Map Request
Build a map request by using the basic WMS URL (http://webservices.nationalatlas.gov/wms?) followed by valid parameter/value pairs separated by an ampersand (&). Table 3 describes the available parameter/value pairs.

 Parameter Description Required/
Optional
 Valid Values  Default Value
SERVICE=WMS The name of the service. In this case, Web Map Service. Required WMS  
REQUEST=GetMap The type of request. Required GetMap  
VERSION=version The version of the requested service. Optional 1.3.0, 1.1.1, 1.1.0, 1.0.7, 1.0.0 1.3.0
FORMAT=output_format Image file format of the map. Required PNG, GIF, JPEG  
WIDTH=output_width Width in pixels of resulting map. Required A valid whole number expressed in pixels.  
HEIGHT=output_height Height in pixels of resulting map. Required A valid whole number expressed in pixels.  
LAYERS=layer_list Comma-separated list of layers to be mapped. The order they are listed in determines drawing order: first in the list = bottom-most layer; last in the list = top-most layer. Required Individually listed in the capabilities file.  

For WMS version 1.3.0:
CRS=EPSG:id_code

For WMS versions 1.1.1 and below:
SRS=EPSG:id_code

Coordinate Reference System (CRS) or Spatial Reference System (SRS) identifier. Required

CRS:84, EPSG:4326, EPSG:2163, EPSG:102100, EPSG:4269, EPSG:4267, EPSG:54004, EPSG:54008, EPSG:3785, EPSG:3857, EPSG:102113, EPSG:900913

The files use the EPSG:4326 projection. We recommend using this value for optimal performance.

 
BBOX=minx,miny,
maxx,maxy
Bounding box corners (lower left, upper right) in SRS units. Required Four comma-delimited numeric values. The full extent of National Atlas layers, in the EPSG:4326 projection, is:
-180,0,0,90
 
TRANSPARENT=value Map’s background transparency. Optional

TRUE, FALSE

Note that the JPG format does not support transparency, so specifying TRANSPARENT=TRUE will have no effect.

TRUE for PNG images; otherwise FALSE
BGCOLOR=color_value Hexidecimal value for the map’s background color. Optional A hexadecimal value, e.g. 0xFFFFFF is white. 0xFFFFFF
STYLES=style_list Comma-separated list of styles. Named styles are not supported, so use "STYLES=" for all map requests. Required; use "&STYLES=" in the parameters list [blank]  
EXCEPTIONS=
exception_format
The format in which exceptions are reported. Optional

The value depends on which WMS version you specify.

For version 1.3.0: XML, INIMAGE, BLANK

For versions 1.1.1 and 1.1.0: application/vnd.ogc.se_xml, application/vnd.ogc.se_inimage, application/vnd.ogc.se_blank

For versions 1.0.7 and 1.0.0: WMS_XML, BLANK, INIMAGE

For version 1.3.0: XML

For versions 1.1.1 and 1.1.0: application/vnd.ogc.se_xml

For versions 1.0.7 and 1.0.0: WMS_XML

Table 3: GetMap Request Parameters

As an example, the following map request will generate the map in Figure 1. Note that the resulting map displays the Seismic Hazard layer ("seihaz") and the States layer ("states").

http://webservices.nationalatlas.gov/wms?SERVICE=WMS&REQUEST=GetMap&VERSION=1.1.1&FORMAT=PNG&
WIDTH=300&HEIGHT=425&SRS=EPSG:4326&BBOX=-125,31,-110,50&LAYERS=seihaz,states

North America map drawn by web mapping services
Figure 1: Example map image

All layers in the National Atlas WMS have unique names. You can find map layer names by accessing the capabilities files in Table 1. The name of the map layer is defined between the Name tag, which is within the Layer tag (Figure 2).

<Layer queryable="1" opaque="0" cascaded="0">
     <Name>seihaz</Name>
     <Title>Geology - Seismic Hazard</Title>
     <EX_GeographicBoundingBox>
          <westBoundLongitude>-179.147</westBoundLongitude>
          <eastBoundLongitude>179.778</eastBoundLongitude>
          <southBoundLatitude>18.9111</southBoundLatitude>
          <northBoundLatitude>71.3892</northBoundLatitude>
     </EX_GeographicBoundingBox>
     <BoundingBox CRS="" minx="-179.147" miny="18.9111" maxx="179.778" maxy="71.3892" />
     <Style>
          <Name>default</Name>
          <Title>default</Title>
          <LegendURL width="71" height="21">
               <Format>image/png</Format>
               <OnlineResource xmlns:xlink="http://www.w3.org/1999/xlink" xlink:type="simple"
                xlink:href="http://webservices.nationalatlas.gov/wms?version=1.3.0
                service=WMS&request=GetLegendGraphic&sld_version=1.1.0&layer=seihaz
                format=image/png&STYLE=default" />
          </LegendURL>
     </Style>
</Layer>
Figure 2: A portion of the Geology GetCapabilities file describing the Seismic Hazard layer. Note the layer name "seihaz" between the Name tags and the title, "Geology - Seismic Hazard," between the Title tags. Also highlighted in bold is the URL for the legend graphic (see the section below for details on the GetLegendGraphic request).

When GetMap parameter values are invalid, an error message will indicate which parameter/value pair is invalid according to the format of the Exceptions type. For example, if you are using WMS version 1.3.0 and if the parameter value EXCEPTIONS = INIMAGE is supplied, then an image that has the error message embedded in it is returned. If the parameter value EXCEPTIONS = BLANK is supplied, then a blank image is returned. If the parameter value EXCEPTIONS = XML or no Exceptions parameter is included, then the error message is returned in XML format.

Getting the Legend Graphic
The URL for the legend graphic is available in the GetCapabilities file between the OnlineResource tag, which is within the LegendURL tag (Figure 2). We suggest you use the legend graphic request supplied in the GetCapabilities file, but you can also build it using the basic WMS URL (http://webservices.nationalatlas.gov/wms?) followed by valid parameter/value pairs separated by an ampersand (&). Table 4 describes the available parameter/value pairs.

 Parameter Description Required/
Optional
 Valid Values  Default Value
SERVICE=WMS The name of the service. In this case, Web Map Service. Required WMS  
REQUEST=
GetLegendGraphic
The type of request. Required GetLegendGraphic  
VERSION=version The version of the requested service. Required 1.3.0, 1.1.1, 1.1.0, 1.0.7, 1.0.0  
LAYER=layer_name The name of the map layer. Required Individually listed in the capabilities file.  
FORMAT=
output_format
Image file format of the legend, listed as a MIME type. Required image/png, image/jpeg, image/gif, image/png; mode=8bit  
SLD_VERSION Version for SLD-specification Required for WMS version 1.3.0, otherwise optional

1.1.0

 
STYLE=style_name Style of layer for which to produce legend graphic. Optional default default
EXCEPTIONS=
exception_format
The format in which exceptions are reported. Optional

The value depends on which WMS version you specify.

For version 1.3.0: XML, INIMAGE, BLANK

For versions 1.1.1 and 1.1.0: application/vnd.ogc.se_xml, application/vnd.ogc.se_inimage, application/vnd.ogc.se_blank

For versions 1.0.7 and 1.0.0: WMS_XML, BLANK, INIMAGE

For version 1.3.0: XML

For versions 1.1.1 and 1.1.0: application/vnd.ogc.se_xml

For versions 1.0.7 and 1.0.0: WMS_XML

Table 4: GetLegendGraphic Request Parameters

Using the Seismic Hazard layer from Figure 1 as an example, the following GetLegendGraphic request will generate the image in Figure 3.

http://webservices.nationalatlas.gov/wms?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetLegendGraphic&
LAYER=seihaz&FORMAT=image/png&STYLE=default

the legend produced by the Get Legend Graphic request
Figure 3: The Legend for the Seismic Hazard Layer

Getting Feature Information
You can get information about features displayed in National Atlas WMS map layers by using the GetFeatureInfo request. A GetFeatureInfo request is much like the GetMap request, but with several additional parameters to specify the point on the map to be queried, which layers to query, and how the output should be displayed. To build a feature information request, start by using the original map request URL, replace the REQUEST parameter with "REQUEST=GetFeatureInfo" and then add the particular GetFeatureInfo paramer/value pairs (separated by "&") as indicated in Table 5. Before building the GetFeatureInfo request, you can check that the layer that interests you can be queried by going to the capabilities file and verifying that queryable=1 in the layer definition.

 Parameter Description Required/
Optional
 Valid Values  Default Value
map request parameters A partial copy of the Map request parameters that generated the map to be queried. The following parameters from the GetMap request are required:VERSION, CRS or SRS, BBOX, WIDTH, HEIGHT, and LAYERS. Required See Table 3, above.  
REQUEST=
GetFeatureInfo
The type of request. Required GetFeatureInfo  
QUERY_LAYERS=
layer_list
Comma-separated list of the layers to be queried. Required Must be one or more of the layers specified in the LAYERS parameter.  

For WMS version 1.3.0:
I=pixel_column

For WMS versions 1.1.1 and below:
X=pixel_column

The horizontal coordinate of the point for which feature information is being requested.

The horizontal dimension is measured as the width of the image returned from the map request, in pixels. I=0 (or X=0 for version 1.1.1 and below) is the coordinate for the left-most pixel, and increases to the right.

Required A valid whole number expressed in pixels. Must be between 0 and the width of the original map image.  

For WMS version 1.3.0:
J=pixel_row

For WMS versions 1.1.1 and below:
Y=pixel_row

The vertical coordinate of the point for which feature information is being requested.

The vertical dimension is measured as the height of the image returned from the map request, in pixels. J=0 (or Y=0 for version 1.1.1 and below) is the coordinate for the top-most pixel, and increases downward.

Required A valid whole number expressed in pixels. Must be between 0 and the height of the original map image.  
INFO_FORMAT=
output_format
The format of the returned query, listed as a MIME type. Required

text/plain, application/vnd.ogc.gml

 
FEATURE_COUNT=
number
The maximum number of features per layer to return. Optional A positive integer ≥ 1. 1
EXCEPTIONS=
exception_format
The format in which exceptions are reported. Optional

The value depends on which WMS version you specify.

For version 1.3.0: XML

For versions 1.1.1 and 1.1.0: application/vnd.ogc.se_xml

For versions 1.0.7 and 1.0.0: WMS_XML

For version 1.3.0: XML

For versions 1.1.1 and 1.1.0: application/vnd.ogc.se_xml

For versions 1.0.7 and 1.0.0: WMS_XML

Table 5: GetFeatureInfo Request Parameters

Using the Seismic Hazard map request from Figure 1 as an example, start with the original GetMap request:

http://webservices.nationalatlas.gov/wms?SERVICE=WMS&REQUEST=GetMap&VERSION=1.1.1&FORMAT=PNG&
WIDTH=300&HEIGHT=425&SRS=EPSG:4326&BBOX=-125,31,-110,50&LAYERS=seihaz,states

To get information about the seismic hazard of a point on the San Francisco peninsula:

The resulting GetFeatureInfo request would be:

http://webservices.nationalatlas.gov/wms?SERVICE=WMS&REQUEST=GetFeatureInfo&VERSION=1.1.1&
FORMAT=PNG&WIDTH=300&HEIGHT=425&SRS=EPSG:4326&BBOX=-125,31,-110,50&LAYERS=seihaz,states&
QUERY_LAYERS=seihaz&X=51&Y=274&INFO_FORMAT=text/plain

and the result, in plain text (Figure 4), indicates a value of 40-60% g for this part of the San Francisco peninsula:

GetFeatureInfo results:

Layer 'seihaz'
  Feature 3394:
    Percent_g = '40 - 60'

Figure 4: Output from the GetFeatureInfo Request