National Digital Forecast
Database (NDFD) Extensible Markup Language (XML) is a service
providing the public, government agencies, and commercial enterprises
with data from the National Weather Service’s (NWS) digital
forecast database. This service, which is defined in a Service
Description Document, provides NWS customers and partners
the ability to request NDFD
data over the internet and receive the information back in
an XML format. The request/response process is made possible
by the NDFD XML Simple Object Access
Protocol (SOAP) server. To see the details of the
NDFD XML SOAP service, go to the following URL and click on the
NDFDgen or NDFDgenByDay link:

In addition to the SOAP technology, this service exploits XML
to enhance the ease with which NWS customers and partners can integrate
NDFD data into their computer applications. XML is a W3C
standard that allows its users to create languages with HTML-like
tags and attributes. The NDFD XML language is called Digital
Weather Markup Language (DWML) and its schema can be found at the
following link:

The schema defines the XML language’s vocabulary (available
tags and attributes) and syntax (expected order of tags). Knowing
how NDFD XML is constructed, users can write programs to process
the XML document to get at the data it contains.

To see a sample Digital Weather Markup Language document that
conforms to the DWML schema, click on any of the following links:

The National Weather Service is striving to serve society’s
needs for weather information by evolving its services from a text-based
paradigm to one based on making NWS information available quickly,
efficiently, and in convenient and understandable forms. The
NDFD is one example of this transformation. NDFD XML takes
yet another step towards a digital services era by making NDFD
data available for computer to computer transfer and processing. NWS
customers and partners can then enhance the value of NDFD data
through the creation of value added products.

The NDFD is updated no more than hourly. We request developers
using this SOAP service for local applications only make a request
for a specific point no more than once an hour. The database is
currently updated by 45 minutes after the hour.

How is NDFD XML generated?

The first step to providing NDFD XML is the creation of the NDFD. For
more information on how NDFD is created, visit the NDFD
home page. With NDFD data available, a user application
creates and sends a SOAP request to the NDFD XML SOAP server. The
SOAP request is processed, creating the DWML document which is
returned to the requesting application for processing. Figure
1 provides a graphical view of the process.

Figure 1. NDFD XML SOAP Process

You can download several simple sample client applications by
clicking on the following links:

NOTE: These clients are examples only and
will not run as is. To run the script, you will need to
install a number of supporting software applications. You
can review the readme
file for additional information on using the sample clients.

What does NDFD XML contain?

NDFD XML contains forecasts for any combination of the following
meteorological parameters:

For additional information on NDFD parameter definitions and available
time projection, please see the NDFD
technical page.

These NDFD parameters can be retrieved in their unsummarized form
using the SOAP server functions NDFDgen() or NDFDgenZip(), or summarized
over either 24- or 12-hourly periods using the functions NDFDgenByDay()
or NDFDgenByDayZip. See the section below titled "How Do You
Use the Web Service?" for more details on these two functions.

The first step to using the web service is to create a SOAP client. The
client creates and sends the SOAP request to the server. The
request sent by the client then invokes one of the server functions. There
are currently nine functions: NDFDgen(), NDFDgenLatLonList(), LatLonListSubgrid(),
LatLonListLine(), LatLonListZipCode(), LatLonListSquare(), CornerPoints(),
NDFDgenByDay(), and NDFDgenByDayLatLonList(). See the tables
below for required following user supplied input:

NDFDgen() function: Returns DWML encoded NDFD data for a
point

Input Name

Type

Example

Description

latitude

Decimal

39.0000

The WGS84 latitude of the point
for which you want NDFD data. North latitude is positive.

longitude

Decimal

-77.0000

The WGS84 longitude of the point
for which you want NDFD data. West longitude is negative.

product

String

time-series

There are two products. The “time-series” product
returns all data between the start and end times for the
selected weather parameters. The “glance” product
returns all data between the start and end times for the
parameters maxt, mint, sky, wx, and icons

startTime

XML Date String

2004-04-27T12:00

The beginning time for which
you want NDFD data. If the string is empty, the start
time is assumed to be the earliest available time in the
database. This input is only needed if one wants to shorten
the time window data is to be retrieved for (less than entire
7 days worth), e.g. if user wants data for days 2-5.

endTime

XML Date String

2004-04-30T12:00

The ending time for which you
want NDFD data. If the string is empty, the end time
is assumed to be the last available time in the database.
This input is only needed if one wants to shorten The time
window data is to be retrieved for (less than entire 7 days
worth), e.g. if user wants data for days 2-5.

Unit

String

e

The unit data is to be retrieved in.
The default value is U.S. Standard, or English units ("e").
A value of "m" will return data in Metric, or SI units (The
International System of Units). If the string is empty, data will
be returned in U.S. Standard units, thus the input is only needed
for metric conversion.

weatherParameters

Array of Booleans

maxt = TRUE

The NDFD parameters that you are
requesting. For valid inputs see the NDFD
Element Names Page.

You can view an example of how to invoke NDFDgen() by selecting "NDFD
Data For Single Point" on the following web page.

List of WGS84 latitude and longitude
pairs for the points for which you want NDFD data. Each
point's latitude and longitude value is seperated by a comma.
Each pair (one latitude and longitude value) is separated
by a space. Number of points requested can not exceed 200.

product

String

time-series

There are two products. The “time-series” product
returns all data between the start and end times for the
selected weather parameters. The “glance” product
returns all data between the start and end times for the
parameters maxt, mint, sky, wx, and icons

startTime

XML Date String

2004-04-27T12:00

The beginning time for which
you want NDFD data. If the string is empty, the start
time is assumed to be the earliest available time in the
database. This input is only needed if one wants to shorten
the time window data is to be retrieved for (less than entire
7 days worth), e.g. if user wants data for days 2-5.

endTime

XML Date String

2004-04-30T12:00

The ending time for which you
want NDFD data. If the string is empty, the end time
is assumed to be the last available time in the database.
This input is only needed if one wants to shorten
the time window data is to be retrieved for (less than entire
7 days worth), e.g. if user wants data for days 2-5.

Unit

String

e

The unit data is to be retrieved in.
The default value is U.S. Standard, or English units ("e").
A value of "m" will return data in Metric, or SI units (The
International System of Units). If the string is empty, data will
be returned in U.S. Standard units, thus the input is only needed
for metric conversion.

weatherParameters

Array of Booleans

maxt = TRUE

The NDFD parameters that you are
requesting. For valid inputs see the NDFD
Element Names Page.

You can view an example of how to invoke NDFDgenLatLonList()
by selecting "NDFD Data For Multiple Points" on the
following web page. NOTE: Number of points requested can not
exceed 200.

The WGS84 latitude of the lower
left point of the rectangular subgrid for which you want
NDFD grid points. North latitude is positive.

lowerLeftLongitude

Decimal

-80.0679

The WGS84 longitude of the lower
left point of the rectangular subgrid for which you want
NDFD grid points. West longitude is negative.

upperRightLatitude

Decimal

33.8835

The WGS84 latitude of the upper
right point of the rectangular subgrid for which you want
NDFD grid points. North latitude is positive.

upperRightLongitude

Decimal

-80.0679

The WGS84 longitude of the upper
right point of the rectangular subgrid for which you want
NDFD grid points. West longitude is negative.

resolution

Decimal

20.0

The default resolution for NDFD data is typically
5km. However, users can request latitude and longitude values
for resolutions greater ( 10km, 15km, 20km, etc.) than the
native resolution so as to reduce the number of points returned.

You can view an example of how to invoke LatLonListSubgrid()
by selecting "Grid Points For Subgrid" on the following
web page.

LatLonListLine() function: Returns the WGS84 latitude and
longitude values for all points on a line defined
by the line's end points. The returned list of points is suitable
for input into NDFDgenLatLonList(), NDFDgenByDayLatLonList(), and
GmlLatLonList() which will return NDFD data for those points. NOTE: The
list of locations will only form a straight line when viewed in
the NDFD projection
applicable to the grid.

Input Name

Type

Example

Description

endPoint1Lat

Decimal

39.0000

The WGS84 latitude of the first
end point of the line for which you want NDFD grid points. North
latitude is positive.

endPoint1Lon

Decimal

-77.0000

The WGS84 longitude of the first
end point of the line for which you want NDFD grid points. West
longitude is negative.

endPoint2Lat

Decimal

39.0000

The WGS84 latitude of the second
end point of the line for which you want NDFD grid points. North
latitude is positive.

endPoint2Lon

Decimal

-77.0000

The WGS84 longitude of the second
end point of the line for which you want NDFD grid points. West
longitude is negative.

You can view an example of how to invoke LatLonListLine() by
selecting "Grid Points For A Line" on the following
web page.

LatLonListZipCode() function: Returns the WGS84 latitude
and longitude values for one
or more zip codes (50 United States and Puerto Rico). The returned
list of points is suitable for input into NDFDgenLatLonList(),
NDFDgenByDayLatLonList(), and GmlLatLonList() which will return
NDFD data for those points.

Input Name

Type

Example

Description

zipCodeList

String

20910

The zip code of the area for
which you want NDFD grid points.

You can view an example of how to invoke LatLonListZipCode()
by selecting "Grid Points For A Zip Code" on the following
web page.

LatLonListCityNames() function: Returns the WGS84 latitude
and longitude values for a predefined list of cities. The cities
are grouped into a number of subsets to facilitate requesting data.
You can view the cities in each group by clicking on the links
in the table below. The returned list of pointsis suitable for
input into NDFDgenLatLonList(), NDFDgenByDayLatLonList(), and GmlLatLonList()
which will return NDFD data for those points.

The WGS84 latitude of the center
or the rectangle for which you want NDFD grid points. North
latitude is positive.

centerPointLon

Decimal

-77.0000

The WGS84 longitude of the center
or the rectangle for which you want NDFD grid points. West
longitude is negative.

distanceLat

Decimal

50.0

The distance from the center
point in the latitudinal direction to the rectangle's East/West
oriented sides.

distanceLon

Decimal

50.0

The distance from the center
point in the longitudinal direction to the rectangle's North/South
oriented side.

resolution

Decimal

20.0

The default resolution for NDFD
data is typically 5km. However, users can request latitude
and longitude values for resolutions greater ( 10km, 15km,
20km, etc.) than the native resolution so as to reduce the
number of points returned.

You can view an example of how to invoke LatLonListSquare()
by selecting "Grid Points For Subgrid (Central Point)" on
the following web page.

CornerPoints() function: Returns the WGS84 latitude and
longitude values for the corners
of an NDFD grid as well as the resolution required to retrieve
the entire grid and still stay under the maximum allowed point
restriction.

Input Name

Type

Example

Description

sector

String

conus

One of the NDFD grids (conus,
alaska, nhemi, guam, hawaii, and puertori).

You can view an example of how to invoke CornerPoints() by selecting "Corner
Grid Points" on the following web page.

List of WGS84 latitude and longitude
pairs for the points for which you want NDFD data. Each
point's latitude and longitude value is seperated by a comma.
Each pair (one latitude and longitude value) is separated
by a space. Number of points requested can not exceed 200.

GML is an Open Geospatial Consortium standard for encoding geospatial
data. One of the advantages of NDFD GML is that it is a recognized
standard. As a result, GML and application schema derived from
it are supported by a number of GIS applications. There are examples
of importing GML-encoded NDFD data into several applications
at the following link.

In addition to GML, the GmlLatLonList() service function can
return Keyhole Markup Language (KML) encoded NDFD data. KML can
be viewed with freely available tools like Google Earth.

GmlTimeSeries() function: Returns Digital Weather GML encoded
NDFD data for a list of points during a user specified time period.

Input Name

Type

Example

Description

listLatLon

string

38.99,-77.02 39.70,-104.80

List of WGS84 latitude and longitude
pairs for the points for which you want NDFD data. Each
point's latitude and longitude value is seperated by a comma.
Each pair (one latitude and longitude value) is separated
by a space. Number of points requested can not exceed 200.

GML is an Open Geospatial Consortium standard for encoding geospatial
data. One of the advantages of NDFD GML is that it is a recognized
standard. As a result, GML and application schema derived from
it are supported by a number of GIS applications. There are examples
of importing GML-encoded NDFD data into several applications
at the following link.

In addition to GML, the GmlLatLonList() service function can
return Keyhole Markup Language (KML) encoded NDFD data. KML can
be viewed with freely available tools like Google Earth.

NDFDgenByDay() function: Returns DWML encoded NDFD data
for a point. Data for each point is summarized for either a 24-
or 12-hour time period

Input Name

Type

Example

Description

latitude

Decimal

39.0000

The WGS84 latitude of the point
for which you want NDFD data. North latitude is positive.

longitude

Decimal

-77.0000

The WGS84 longitude of the point
for which you want NDFD data. West longitude is negative.

startDate

XML Date String

2004-04-27

The beginning day for which you
want NDFD data. If the string is empty, the start
date is assumed to be the earliest available day in the database.
This input is only needed if one wants to shorten the time window
data is to be retrieved for (less than entire 7 days worth), e.g.
if user wants data for days 2-5.

numDays

Integer

7

The number of days worth of NDFD
data you want. Default will be all available data in the database.
This input is only needed if one wants to shorten the time window
data is to be retrieved for (less than entire 7 days worth), e.g.
if user wants data for days 2-5.

Unit

String

e

The unit data is to be retrieved in.
The default value is U.S. Standard, or English units ("e").
A value of "m" will return data in Metric, or SI units (The
International System of Units). If the string is empty, data will
be returned in U.S. standard units, thus the input is only needed
for metric conversion.

format

String

12 hourly

There are two formats. The “24
hourly” format returns NDFD data summarized for a 24
hour period running from 6:00 AM to 6:00 AM. The “12
hourly” format summarizes NDFD data into two 12 hour
periods per day that run from 6:00 AM to 6:00 PM and 6:00
PM to 6:00 AM

You can view an example of how to invoke NDFDgenByDay() by selecting "NDFD
Data For Single Point" on the following web page.

NDFDgenByDayLatLonList() functionReturns DWML encoded NDFD
data for a list of points. Data for each point is summarized for
either a 24- or 12-hour time period

Input Name

Type

Example

Description

listLatLon

Decimal

38.99,-77.02
39.70,-104.80

List of WGS84 latitude and longitude
pairs for the points for which you want NDFD data. Each
point's latitude and longitude value is seperated by a comma.
Each pair (one latitude and longitude value) is separated
by a space. Number of points requested can not exceed 200.

startDate

XML Date String

2004-04-27

The beginning day for which you
want NDFD data. If the string is empty, the start
date is assumed to be the earliest available day in the database.

numDays

Integer

7

The number of days worth of NDFD
data you want.

Unit

String

e

The unit data is to be retrieved in.
The default value is U.S. Standard, or English units ("e").
A value of "m" will return data in Metric, or SI units (The
International System of Units). If the string is empty, data will
be returned in U.S. standard units, thus the input is only needed
for metric conversion.

format

String

12 hourly

There are two formats. The “24
hourly” format returns NDFD data summarized for a 24
hour period running from 6:00 AM to 6:00 AM. The “12
hourly” format summarizes NDFD data into two 12 hour
periods per day that run from 6:00 AM to 6:00 PM and 6:00
PM to 6:00 AM

You can view an example of how to invoke NDFDgenByDayLatLonList()
by selecting "NDFD Data For Multiple Points" on the
following web page. NOTE: Number of points requested can not
exceed 200.

Once the SOAP server returns the XML document back to the client,
you can then parse the DWML using SAX,
the DOM,
or XSLT.

All latitude and longitude values provided as input or in the
output DWML are based on the World Geodetic System 1984 (WGS84).
For more inforation on the NDFD spatial reference system see the NDFD
Spatial Reference System page.

Please note: There is an NDFD Web Services user forum that
might be able to help developers with implementation language specific
issues. The unofficial forum can be found at the following URL:

The NWS has developed a program called degrib that can output
NDFD data encoded in DWML. Degrib is a C program that allows you
to visualize NDFD GRIB2 data and convert these binary files into
other formats. If you are a web service user who wants DWML-encoded
data for a large number of NDFD points, degrib will allow you to
move the DWML-encoding process to your computer. By using degrib
to process the NDFD data on a local computer, you may be able to
significantly improve the speed with which your program is able
to ingest NDFD data. The NWS makes a degrib executable available
for Microsoft Windows PCs and the degrib source code available
for compilation on other computer operating systems. To download
degrib software, visit the URL http://www.nws.noaa.gov/mdl/degrib/register.php.
Once you have the degrib software running, you will need to maintain
updated NDFD GRIB2 files. For more information on downloading NDFD
GRIB2 files from the NWS Telecommunication Operations Center, see
the URL http://www.nws.noaa.gov/mdl/degrib/dataloc.php.
For additional help on using degrib to convert NDFD GRIB2 files
into DWML see the degrib
tutorial and man
page.

Below are listed recent change notices for NWS XML services. A
complete listing is available.
An RSS feed of the change notices
is also available. These notices are used to announce major changes,
schema changes and new services.

NDFD-XML: Updated the degrib executable and ndfdXMLserver.php and the wsdl: ndfdXML.wsdl, for NDFD Web Service to address missing elements (maxrh, minrh, iceaccum, 6 Tropical wind threshold probabilities).Mar 13, 2014 at 11AM Easter Time. A new deployment of the NDFD REST And SOAP Web Service will be implemented to address Maximum Relative Humidity, Minimum Relative Humidity, and Ice Accumulation not dissiminating via the Web Service. They have been added to the weatherParameters array in ndfdXMLserver.php file. Also, 2 defunct elements, the tstmprb and tstmcat, were removed from the ndfdXML.wsdl file. Also, there was a long standing issue with the 6 Tropical Wind Threshold Probability elements (incw34, incw50, incw64, cumw34, cumw50, cumw64) causing Seg Faults depending on list of point's in query, or a doubling up of the data.NDFD-XML: New NDFD SOAP/REST XML Web Service Install Tuesday June 19th, 2012On Tuesday, June 19th, MDL will install a new version of the NDFD SOAP/REST XML Web Service.
The release is for the addition of two new NDFD elements: Maximum and Minimum Daily Relative Humidity.
This should not interrupt services, except for those who have scripts in which every parameter must be denoted:
i.e., for a new SOAP Request, the following will need to be added: -------------------------------------------------------------------------------------------------------------------------
maxrh xsi:type="xsd:boolean">0 /maxrh> ------
minrh xsi:type="xsd:boolean">0 /minrh>
--------------------------------------------------------------------------------------------------------------------------------
On Mon June 18th or Tuesday June 19th, as the time of the switchover becomes clear, we will send out another email, we will post
the information on the NDFD Web Service yahoo list forum at http://tech.groups.yahoo.com/group/NDFD_SOAP_Service/
and post the information here in xml_changes.xml (http://graphical.weather.gov/xml/xml_changes.xml and http://graphical.weather.gov/xml/xml_change_notices.php)
Please use the following channels to let us know of any problems accessing the NDFD Web Service immediately after the switch:
1) Email the NIDS support crew at nids.support@noaa.gov -----------------------------------------------
2) Open up a trouble ticket with the National Weather Service Telecommunication Gateway's TOC (Traffic Operations
Center) at toc.nwstg@noaa.gov -------------------------------------------------
3) Use the NDFD Web Service yahoo list forum to report issues: http://tech.groups.yahoo.com/group/NDFD_SOAP_Service/NDFD-XML: Maximum and Minimum Relative Humidity added to NDFD Web ServiceTwo new Fire Weather elements, Maximum and Minimum Relative Humidity, will be added for dissimination through the NDFD Web Service. For more information see the Technical Implementation Notice (TIN).
The name of the elements are "maxrh" and "minrh", seen here in the WSDL (http://graphical.weather.gov/xml/SOAP_server/ndfdXMLserver.php?wsdl).