National Digital Forecast Database (NDFD) Simple Object Access Protocol (SOAP)
and Representational State Transfer (REST) XML Web Service

What is NDFD XML (DWML and TSML)?

The National Digital Forecast Database (NDFD) Extensible Markup Language (XML) Web Service provides 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 the original 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 (Note, many updates, including a REST service, and an additional XML encoding standard, have been added to the NDFD XML Web Service since the original Service Description Document was drafted). The request/response process is made possible by the NDFD XML Simple Object Access Protocol (SOAP) server or Representational State Transfer (REST).

To see the details of the NDFD XML SOAP service, go to the following server link and click on NDFDgen or NDFDgenByDay:

https://digital.weather.gov/xml/SOAP_server/ndfdXMLserver.php

If the web service description provided by the SOAP server does not meet your needs, similar information is available in the following Web Service Description Language (WSDL) document:

https://digital.weather.gov/xml/wsdl/ndfdXML.wsdl

This NDFD Web Service uses XML to enhance the ease with which NWS customers, partners, and other clients, 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.

XML schemas define the language’s vocabulary (available tags and attributes) and syntax (expected order of tags) used to encode the NDFD data returned from the web service. Knowing how NDFD XML is constructed, users can write programs to process the XML document to extract the data it contains.

Two different encoding formats of XML: DWML and TSML

1) Digital Weather Markup Language (DWML)

https://digital.weather.gov/xml/schema/DWML.xsd

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

latest_DWML_time-series.txt
latest_DWML_glance.txt
latest_DWML_Summary-24hr.txt
latest_DWML_Summary-12hr.txt

2) Timeseries Markup Language (TSML)

The TSML schemas can be found at the following link. The TSML schema version currently used is 1.2

http://schemas.opengis.net/tsml

To see a sample TSML document that conforms to the TSML schemas, click on any of the following links:

latest_TSML_time-series.txt
latest_TSML_glance.txt
latest_TSML_Summary-24hr.txt
latest_TSML_Summary-12hr.txt

Why provide an NDFD XML Web Service?

The National Weather Service is striving to serve society’s needs for weather and climate 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. The NDFD XML Web Service 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.

You can provide comments on this web service from the following page:

https://www.weather.gov/contact

How often is NDFD XML data updated?

The NDFD is updated two times per hour. We request developers using this web service for local applications only make a request for a specific point no more than twice an hour. The database is currently updated by 25 and 55 minutes after the hour.

How is NDFD XML data generated?

The first step to providing NDFD XML data is the creation of the NDFD. For more information on how NDFD is created, visit the NDFD home page.

SOAP:

Figure 1.   NDFD XML Web Service SOAP Process

REST:

What does the NDFD XML Web Service contain?

The Web Service returns forecasts for any combination of the following meteorological and climatological elements listed here:

https://vlab.noaa.gov/documents/6609493/7858379/NDFDStatus.pdf

A quick list of the NDFD elements that can be queried for in this version of the NDFD XML Web Service is here: NDFD Element Names

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

In addition to its meteorological content, the NDFD XML returned also contains meta data about the product. For returned data encoded in DWML, a description of the meta data as well as data XML tags and attributes can be found in the Digital Weather Markup Language Specification [PDF] [HTML] [DOC]

Finally, a list of all possible fields for icons and the weather conditions can be found here: NDFD Web Service's Icon/Weather Conditions XML fields.

How Do You Use the Web Service?

For REST, please visit the NDFD XML Web Service REST Home page

SOAP:

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 user supplied input consisting of the input query parameter names, and their resulting values:

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



Input Query Name	Type	Example Value	Description
latitude	Decimal	39.21	The WGS84 latitude of the point for which you want NDFD data. North latitude is positive.
longitude	Decimal	-77.08	The WGS84 longitude of the point for which you want NDFD data. West longitude is negative.
product	string	time-series, glance	There are two products. The “time-series” product returns all data between the start and end times for the user selected weather parameters in the weatherParameters input query below. The “glance” product returns all data between the start and end times for the parameters maxt, mint, sky, wx, icons, and wwa (hazards), by default. Note, when the “glance” (“Weather at a Glance”) product is chosen, a choice of elements is not permitted.
startTime	XML Date string	2020-04-27T12:00: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	2020-04-30T12:00: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, m	The unit data is to be formatted 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. Set value to 1 for parameters wanted.
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

You can view an example of how to invoke NDFDgen() by selecting "NDFD Data For Single Point" on the following web page, which represents a URL client to the SOAP service.

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the NDFDgen() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/NDFDgen.xml

NDFDgenLatLonList() function: Returns DWML or TSML encoded NDFD data for a list of points



Input Query Name	Type	Example Value	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. To reduce resources on the web service, the number of points requested can not exceed 100.
product	string	time-series, glance	There are two products.   The “time-series” product returns all data between the start and end times for the selected weather parameters in the weatherParameters input query below.   The “glance” product returns all data between the start and end times for the parameters maxt, mint, sky, wx, icons, and wwa (hazards). Note, when the “glance” (“Weather at a Glance”) product is chosen, a choice of elements is not permitted.
startTime	XML Date string	2020-04-27T12:00: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	2020-04-30T12:00: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, m	The unit data is to be formatted 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. Set value to 1 for parameters wanted.
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

You can view an example of how to invoke NDFDgenLatLonList() by selecting "NDFD Data For Multiple Points" on the following web page, which represents a URL client to the SOAP server. To reduce resources on the web service, the number of points requested can not exceed 100.

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the NDFDgenLatLonList() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/NDFDgenLatLonList.xml

LatLonListSubgrid() function: Returns the WGS84 latitude and longitude values of all the NDFD grid points within a rectangular subgrid as defined by points at the lower left and upper right corners of the rectangle. The returned list of points is suitable for input into NDFDgenLatLonList(), NDFDgenByDayLatLonList(), and GmlLatLonList() which will return NDFD data for those points. NOTE: The subgrid locations will only form a rectangle when viewed in the NDFD projection applicable to the grid.



Input Query Name	Type	Example Value	Description
lowerLeftLatitude	Decimal	33.88	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.06	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.88	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.06	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 2.5km. However, users can request latitude and longitude values for resolutions greater ( 5km, 10km, 15km, 20km, etc.) than the native resolution so as to reduce the number of points returned.
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

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

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the LatLonListSubgrid() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/LatLonListSubgrid.xml

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 Query Name	Type	Example Value	Description
endPoint1Lat	Decimal	39.00	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.00	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.00	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.00	The WGS84 longitude of the second end point of the line for which you want NDFD grid points.   West longitude is negative.
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

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

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the LatLonListLine() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/LatLonListLine.xml

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 Query Name	Type	Example Value	Description
zipCodeList	string	20910	The zip code of the area for which you want NDFD grid points.
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

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

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the LatLonListZipCode() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/LatLonListZipCode.xml

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 points is suitable for input into NDFDgenLatLonList(), NDFDgenByDayLatLonList(), and GmlLatLonList() which will return NDFD data for those points.



Input Query Name	Type	Example Value	Description
citiesLevel	Integer	12	1 = Primary Cities Diagram (list of cities here). 2 = Secondary Cities Diagram (list of cities here). 3 = Cities that increase data density across the US, Diagram (cities 1 - 200), (list of cities here). 4 = Cities that increase data density across the US, Diagram (cities 201 - 304), (list of cities here). 12 = Combines cities in 1 and 2 above, Diagram (list of cities here). 34 = Combines cities in 3 and 4 above, Diagram (list of cities here). 1234 = Combines cities in 1, 2, 3, and 4 above, Diagram (list of cities here).
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

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

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the LatLonListCityNames() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/LatLonListCityNames.xml

LatLonListSquare() function: Returns the WGS84 latitude and longitude values for a rectangle defined by a center point and distances in the latitudinal and longitudinal directions. The returned list of points is suitable for input into NDFDgenLatLonList(), NDFDgenByDayLatLonList(), and GmlLatLonList() which will return NDFD data for those points. NOTE: The subgrid locations will only form a rectangle when viewed in the NDFD projection applicable to the grid.



Input Query Name	Type	Example Value	Description
centerPointLat	Decimal	39.00	The WGS84 latitude of the center or the rectangle for which you want NDFD grid points.   North latitude is positive.
centerPointLon	Decimal	-77.00	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 2.5km. However, users can request latitude and longitude values for resolutions greater ( 5km, 10km, 15km, 20km, etc.) than the native resolution so as to reduce the number of points returned.
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

You can view an example of how to invoke LatLonListSquare() by selecting "Grid Points For Subgrid (Central Point)" on the following web page, which represents a URL client to the SOAP server.

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the LatLonListSquare() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/LatLonListSquare.xml

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 Query Name	Type	Example Value	Description
sector	string	conus	One of the NDFD grids (conus, alaska, nhemi, guam, hawaii, npacocn, and puertori).
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

You can view an example of how to invoke CornerPoints() by selecting "Corner Grid Points" on the following web page, which represents a URL client to the SOAP server.

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the CornerPoints() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/CornerPoints.xml

GmlLatLonList() function: Returns Digital Weather Geography Markup Language (GML) encoded NDFD data for a list of points at a single valid time.



Input Query Name	Type	Example Value	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. To reduce resources on the web service, the number of points requested can not exceed 100.
requestedTime	XML Date string	2020-04-27T12:00:00	The time for which you want NDFD data.
featureType	string	Forecast_Gml2Point	GML 2 Compliant Data Structure: Forecast_Gml2Point GML 3 Compliant Data Structures: Forecast_GmlsfPoint, Forecast_GmlObs, NdfdMultiPointCoverage KML 2 Compliant Data Structure: Ndfd_KmlPoint
weatherParameters	Array of Booleans	maxt = TRUE	The NDFD parameters that you are requesting.   For valid inputs see the NDFD Element Names Page. Set value to 1 for parameters wanted.

You can view an example of how to invoke GmlLatLonList() by selecting "NDFD Data Encoded in GML for Single Time" on the following web page, which represents a URL client to the SOAP server. To reduce resources on the web service, the number of points requested can not exceed 100.

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the GmlLatLonList() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/GmlLatLonList.xml

GML is also an OGC International Standard for encoding geospatial data. As a result, GML and the 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 tutorials link:


Tutorials on integrating the NDFD Web Service and clients like ArcGIS, Google Earth, and Google Maps.

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 and is also recognized by the OGC.

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



Input Query Name	Type	Example Value	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. To reduce resources on the web service, the number of points requested can not exceed 100.
startTime	XML Date string	2020-01-01T14:00:00	The start time for which you want NDFD data.
endTime	XML Date string	2020-01-05T23:00:00	The end time for which you want NDFD data.
compType	string	Between	Comparison type. Can be IsEqual, Between, GreatThan, GreaterThanOrEqual, LessThan, or LessThanOrEqual.
featureType	string	Forecast_Gml2Point	GML 2 Compliant Data Structure: Forecast_Gml2Point GML 3 Compliant Data Structures: Forecast_GmlsfPoint, Forecast_GmlObs, NdfdMultiPointCoverage KML 2 Compliant Data Structure: Ndfd_KmlPoint
propertyName	comma delimited list	maxt,mint,wx	The NDFD element that you are requesting.   For valid inputs see the NDFD Element Names Page. Set value to 1 for parameters wanted.

You can view an example of how to invoke GmlTimeSeries() by selecting "NDFD Data Encoded in GML for Time Period" on the following web page, which represents a URL client to the SOAP server. To reduce resources on the web service, the number of points requested can not exceed 100.

https://digital.weather.gov/xml/SOAP_server/ndfdXML.htm

You can see a sample SOAP request for the GmlLatLonList() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/GmlTimeSeries.xml

GML is also an OGC International Standard for encoding geospatial data. As a result, GML and the 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 tutorials link:


Tutorials on integrating the NDFD Web Service and clients like ArcGIS, Google Earth, and Google Maps.

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 or TSML encoded NDFD data for a point. Data for each point is summarized over either 24- or 12-hour forecast time periods.

NOTE: There is no choice by user of meteorological elements for these summarization functions. The following summarized elements are always returned by default: Maximum Temperature, Minimum Temperature, 12 Hourly Probability of Precipitation, Weather, Icons, and Hazards (Watches, Warnings, and Advisories).




Input Query Name	Type	Example Value	Description
latitude	Decimal	39.00	The WGS84 latitude of the point for which you want NDFD data.   North latitude is positive.
longitude	Decimal	-77.00	The WGS84 longitude of the point for which you want NDFD data.   West longitude is negative.
startDate	XML Date string	2020-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, m	The unit data is to be formatted 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, 24 hourly	There are two formats.   The “24 hourly” format returns NDFD data summarized for a 24 hour forecast period running from 6:00 AM to 6:00 AM.   The “12 hourly” format summarizes NDFD data into two 12 hour forecast periods per day that run from 6:00 AM to 6:00 PM and 6:00 PM to 6:00 AM
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

You can view an example of how to invoke NDFDgenByDay() by selecting "NDFD Data For Single Point" on the following web page, which represents a URL client to the SOAP server.

https://digital.weather.gov/xml/SOAP_server/ndfdSOAPByDay.htm

You can see a sample SOAP request for the NDFDgenByDay() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/NDFDgenByDay.xml

NDFDgenByDayLatLonList() function: Returns DWML or TSML encoded NDFD data for a list of points. Data for each point is summarized over either 24- or 12-hour forecast time periods.

NOTE: There is no choice by user of meteorological elements for these summarization functions. The following summarized elements are always returned by default: Maximum Temperature, Minimum Temperature, 12 Hourly Probability of Precipitation, Weather, Icons, and Hazards (Watches, Warnings, and Advisories).




Input Query Name	Type	Example Value	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. To reduce resources on the web service, the number of points requested can not exceed 100.
startDate	XML Date string	2020-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, m	The unit data is to be formatted 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, 24 hourly	There are two formats.   The “24 hourly” format returns NDFD data summarized for a 24 hour forecast period running from 6:00 AM to 6:00 AM.   The “12 hourly” format summarizes NDFD data into two 12 hour forecast periods per day that run from 6:00 AM to 6:00 PM and 6:00 PM to 6:00 AM
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

You can view an example of how to invoke NDFDgenByDayLatLonList() by selecting "NDFD Data For Multiple Points" on the following web page, which represents a URL client to the SOAP server. To reduce resources on the web service, the number of points requested can not exceed 100.

https://digital.weather.gov/xml/SOAP_server/ndfdSOAPByDay.htm

You can see a sample SOAP request for the NDFDgenByDayLatLonList() interface at
https://digital.weather.gov/xml/docs/SOAP_Requests/NDFDgenByDayLatLonList.xml

NDFDgenByDayMultiCities() function: Returns DWML or TSML encoded NDFD data 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 under Description in the table below. Data for each point is summarized over either 24- or 12-hour forecast time periods.

NOTE: There is no choice by user of meteorological elements for these summarization functions. The following summarized elements are always returned by default: Maximum Temperature, Minimum Temperature, 12 Hourly Probability of Precipitation, Weather, Icons, and Hazards (Watches, Warnings, and Advisories).


a

Input Query Name	Type	Example Value	Description
citiesLevel	Integer	12	1 = Primary Cities Diagram (list of cities here). 2 = Secondary Cities Diagram (list of cities here). 3 = Cities that increase data density across the US, Diagram (cities 1 - 200), (list of cities here). 4 = Cities that increase data density across the US, Diagram (cities 201 - 304), (list of cities here). 12 = Combines cities in 1 and 2 above, Diagram (list of cities here). 34 = Combines cities in 3 and 4 above, Diagram (list of cities here). 1234 = Combines cities in 1, 2, 3, and 4 above, Diagram (list of cities here).
startDate	XML Date string	2020-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. If the string is empty, numDays is assumed to be the full amount of days 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, m	The unit data is to be formatted in. The default value is U.S. Standard, or English units ("e"). A string 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, 24 hourly	There are two formats.   The “24 hourly” format returns NDFD data summarized for a 24 hour forecast period running from 6:00 AM to 6:00 AM.   The “12 hourly” format summarizes NDFD data into two 12 hour forecast periods per day that run from 6:00 AM to 6:00 PM and 6:00 PM to 6:00 AM
XMLformat	string	DWML, TSML	The XML encoding type data is returned in. Value can be either TSML or DWML. If not specified, the default value is DWML.

You can view an example of how to invoke NDFDgenByDayMultiCities() by selecting "NDFD Data For NDFD Cities" on the following web page, which represents a URL client to the SOAP server.

https://digital.weather.gov/xml/SOAP_server/ndfdSOAPByDay.htm

Once the SOAP server returns the XML document back, the client can then parse the XML using any number of open source software packages.

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

NDFD XML Web Service Constraints, Guidelines, and Best Practices

The NDFD XML Web Services REST page

Please visit the following web page to access the Web Service via REST:

NDFD XML Web Service REST Home page

WHAT'S NEW: NWS XML Web Services Change Notices

Below are listed recent updates and change notices for the NWS NDFD XML Web Service. A complete listing is available. An RSS feed of the change notices is also available. These notices are used to announce major changes such as resolution changes, schema changes, new services, new meteorological elements offered, etc.

NDFD-XML: Five Experimental Aviation Weather Elements added to NDFD XML Web Service
Five new Aviation elements will be added for dissemination through the NDFD XML Web Service. They will be available for points in the Conus and Puerto Rico sectots. For more information see the Product Description Document (PDD). These experimental elements will be available for comment through May 23, 2023. These elements include Ceiling Height (defined as the lowest cloud base, measured in feet, where the cumulative sky cover is > 50%, and uses the threshold for the qualitative term “broken” or “BKN”), Visibility (values are consistent with information in the weather and hazard grids. Units are statute miles (SM) with a resolution of 0.25 SM from 0 to 1.50, inclusive, and a resolution of SM from 2 to 10 SM, inclusive. Values > 10 SM are set to 10 SM), and Low Level Wind Shear. There are 3 separate Low Level Wind Shear elements: Height (the top of the low-level wind shear layer), Wind Speed, and Wind Direction. The name of the elements in the service are "ceil", "vis", "llwsdist", "llwswindspd", and "llwswinddir", as seen here in the WSDL (https://digital.weather.gov/xml/SOAP_server/ndfdXMLserver.php?wsdl).

NDFD-XML: New AWS NDFD XML Web Service (digital.weather.gov/xml) to limit the number of lat/lon points in a query to 100 to limit resource strain on the web service. For more information, see our NDFD XML Web Service Use Guidelines page at https://digital.weather.gov/xml/mdl/XML/Design/WebServicesUseGuidelines.php.


NDFD-XML: AWS NDFD XML Web Service at Full Resolution
The new NDFD XML Web Service (digital.weather.gov/xml) is at full resolution for points queried in the CONUS sector. The spatial and temporal resolution in the NDFD as compared to the operational system on graphical (graphical.weather.gov/xml) will be available at 2.5km spatial resolution for all forecast times and at 1 hour temporal resolution for the first 36 hours from NDFD issuance time (on graphical, the spatial resolution is 5km and 3 hourly). These are the finest spatial and temporal resolutions at which Weather Forecast Offices in the Conterminous United States (CONUS) provide forecasts. More information is here in the Technical Implementation Notice and also: here.

NDFD-XML: AWS NDFD XML Web Service to offer a new XML format encoding for the NDFD XML Web Service: Time Series Markup Language (TSML).
The new AWS version of the NDFD XML Web Service (digital.weather.gov/xml) will offer TSML as an encoding option. This second option of XML formatting is an Open Geospatial Consortium (OGC) recognized International encoding Standard, unlike DWML. Because of this, TSML offers greater interoperability: the ability of different information systems, products, or applications, whose interfaces are understood, to connect with other products or systems. TSML also defines the semantics of observational (in the NDFD case, forecast) data as a timeseries for data exchange. TSML profiles the Observations and Measurements standard to define a result of type timeseries. TSML allows the encoding of many latitude/longitude points as a collection (tsml:Collection) of observation members with each geographic point denoted as the feature of interest. The TSML schemas can be found at http://schemas.opengis.net/tsml. The TSML schema version currently used is 1.2. To return XML encoded in TSML, there is a new query parameter 'XMLformat'. This query parameter must be set to TSML in the request. If XMLformat is not used at all, it defaults to the older DWML encoding.

NDFD-XML: RTMA elements removed from AWS NDFD XML Web Service
The 6 Real Time Mesoscale Analysis elements, and 4 associated uncertainties, will be removed from the new AWS NDFD XML web service (digital.weather.gov/xml). These are Real-time Mesoscale Analysis Precipitation (precipa_r), Real-time Mesoscale Analysis GOES Effective Cloud Amount (sky_r), Real-time Mesoscale Analysis Dewpoint Temperature (td_r), Real-time Mesoscale Analysis Temperature (temp_r), Real-time Mesoscale Analysis Wind Direction (wdir_r), Real-time Mesoscale Analysis Wind Speed (wspd_r), Real-time Mesoscale Analysis Error/Uncertainty for Temperature (utemp), Real-time Mesoscale Analysis Error/Uncertainty for Dewpoint Temperature (utd), Real-time Mesoscale Analysis Error/Uncertainty for Wind Speed (uwspd), and Real-time Mesoscale Analysis Error/Uncertainty for Wind Direction (uwdir).

NDFD-XML: Snow Ratio added to NDFD XML Web Service
The new Snow Ratio element will be added for dissemination through the NDFD XML Web Service. For more information see the Product Description Document (PDD). This element will be available throughout the winter season. This element is defined as the ratio of snow accumulation to its melted liquid equivalent. The name of the element in the service is "snowratio", as seen here in the WSDL (https://digital.weather.gov/xml/SOAP_server/ndfdXMLserver.php?wsdl).

Information on different NDFD XML web service versions

URLs that begin with 'graphical.weather.gov/xml' go to the coarse-resolution (3-hour, 5km) legacy operational NWS servers. This service has NDFD elements that were operationally available when upgrades to this on-prem service were frozen about 2016. A list of elements available for this version of the NDFD XML Web Service is here: NDFD Elements on graphical

URLs that begin with 'preview.weather.gov/xml' go to the fine-resolution (1-hour, 2.5km) experimental on-prem NWS servers. This has all NDFD elements available at lower resolution on graphical, in higher resolution form. It also contains NDFD elements that were experimentally available at finer resolution when upgrades to the on-prem service on graphical were frozen about 2016. A list of elements available for this version of the NDFD XML Web Service is here: NDFD Elements on preview

In response to performance issues on both on-prem XML web services listed above (graphical and preview), the NWS was testing NDFD XML web services for new NDFD elements on Amazon Web Services (AWS). For more information, see: NDFD on AWS. The AWS version of the NDFD XML web service is this current one, hosted on this page at https://digital.weather.gov/xml/. Prior, to April 2022, it disseminated only those elements (20) the NDFD had developed since 2016. It also did not disseminate the "Weather At A Glance", 12 hourly, or 24 hourly summary products.

URLs that begin with 'digital.weather.gov/xml', as of April 2022, now access the fine-resolution (1-hour, 2.5km) prototype servers on AWS. This service now provides the newer (post-2016) NDFD elements that are not available via the on-prem (graphical and preview) NWS services. It also contains the full suite of all available NDFD elements. A list of the NDFD elements available for this version of the NDFD XML Web Service is here: NDFD Elements on digital

Point of Contact Information for NDFD XML Web Service Issues

To submit a ticket for an issue with the NWS XML Web Services, please email the NOAA ServiceNow Platform at nsdesk@midatl.service-now.com.