National Digital Forecast Database (NDFD)
Experimental
Recently Updated Grids Service (RUGS)

The evaluation and comment period for the “Recently Updated Grids Service” is extended through September 30, 2011, effective December 13, 2010. The comment period is in compliance with NWSI-10-102 and during this period, we encourage your comments or suggestions for improvements using the electronic survey provided. Your feedback will help us determine service utility, if modifications are needed, and whether the service should become part of our operational suite. To provide feedback, you can use the Customer Survey for Experimental Products/Services at the following URL:

http://www.weather.gov/survey/nws-survey.php?code=RUGS

In addition to completing the survey on-line, it can be e-mailed to nws.xml@noaa.gov or mailed to the following address:

Meteorological Development Laboratory
Attn: Carl McCalla, Sr., W/OST24
1325 East-West Highway, SSMC2
Silver Spring, MD 20910

The RUGS Service Description Document is available at the following URL:

http://products.weather.gov/PDD/NDFD_RUGS_Nov10.pdf

1. What is RUGS?
2. Why provide RUGS?
3. How often is RUGS data updated?
4. What does a RUGS response contain?
5. How Do You Use RUGS?

What is RUGS?

RUGS is an experimental Hypertext Transfer Protocol (HTTP) based service allowing a user to determine if National Digital Forecast Database (NDFD) General Regularly-distributed Information in Binary form (GRIB2) files have been updated. RUGS returns an Atom Syndication Format (Atom) document containing the URL of modified GRIB2 files that conform to the user request. Users employ the following input variables to constrain which GRIB2 files are evaluated for updates.

• locationType
• locations
• elements
• issuanceSearchTime
• searchStartTime
• searchEndTime
• showChangedTimes

Why provide RUGS?

NDFD users who download GRIB2 files can use RUGS to only retrieve files that have been recently update. Downloading only modified files should save the user communication and computer processing resources.

How often is RUGS data updated?

The data available to RUGS is updated hourly. We request developers using this service submit request no more than once an hour.

What does a RUGS response contain?

The RUGS response is formatted as an Atom document which contains a number of Atom and locally defined elements that users can parsed to extract information about updated NDFD GRIB2 files. The following link takes you to a page describing the elements user can expect to find in a RUGS response document.

RUGS Elements

How Do You Use RUGS?

The simplist way to use RUGS is to submit a request using the following web page:

https://bestpractices.nws.noaa.gov/mdl/RUGS/recentlyUpdatedGrids.htm

Since RUGS is designed for machine-to-machine use, the more common way to use the service is by creating an application that submits an HTTP request using the GET method.

The client program would format and submit a query string that looks similar to the following examples:

For a Weather Forecast Office (WFO) type location

https://bestpractices.nws.noaa.gov/mdl/RUGS/recentlyUpdatedGrids.php?
locationType=wfo&
locations=BOX,MOB,SEW&
elements=maxt,mint,temp&
issuanceSearchTime=2004-01-01T00:00:00&
searchStartTime=2004-01-01T00:00:00&
searchEndTime=2012-11-25T00:00:00&
showChangedTimes=no

For a Sector type location

https://bestpractices.nws.noaa.gov/mdl/RUGS/recentlyUpdatedGrids.php?
locationType=sector&
locations=crgrlake,ergrlake,crmissvy&
elements=maxt,mint,temp&
issuanceSearchTime=2004-01-01T00:00:00&
searchStartTime=2004-01-01T00:00:00&
searchEndTime=2012-11-25T00:00:00&
showChangedTimes=yes

For a State type location

https://bestpractices.nws.noaa.gov/mdl/RUGS/recentlyUpdatedGrids.php?
locationType=state&
locations=TX,VA,UT&
elements=maxt,mint,temp&
issuanceSearchTime=2004-01-01T00:00:00&
searchStartTime=2004-01-01T00:00:00&
searchEndTime=2012-11-25T00:00:00&
showChangedTimes=yes

For a Point type location

https://bestpractices.nws.noaa.gov/mdl/RUGS/recentlyUpdatedGrids.php?
locationType=point&
locations=34.1^118.4,40.7^-111.9,40.67^-73.94&
elements=maxt,mint,temp&
issuanceSearchTime=2004-01-01T00:00:00&
searchStartTime=2004-01-01T00:00:00&
searchEndTime=2012-11-25T00:00:00&
showChangedTimes=yes

More information on the input parameters can be found using the following links:

• locationType
• locations
• elements
• issuanceSearchTime
• searchStartTime
• searchEndTime
• showChangedTimes

Using the returned RUGS response, the user will parse the <content> element found in each of the one or more <entry> elements. The "src" attribute of the <content> element contains the URL to each updated file.

Finally, the client program would download the updated GRIB2 files, using the URL in the <content> element, for use within some user particular process.

Location Type Input

Users can provide RUGS location input in the following four forms. The user indicates which location type they are using is their request (e.g. locationType=wfo).

Location Input

RUGS needs to know what portion of the NDFD the user wants searched. The "location" input is used to convey the geographical area of interest. The location input must be consistent with the "locationType" input. If the user is interested in more than one location, each location is included in a comma delimited list (e.g. location=BOX,AUS,SEW). The following sections describe location input appropriate for each location type.

WFO Name Input

RUGS users can monitor changes to the GRIB2 file that completely contains an NWS WFO. The page at the following link contains valid WFO identifiers.

WFO Identifiers

3-letter WFO identifiers are not case sensitive (i.e. they may be upper, lower, or mixed case). Several examples of WFO input follow:

• LWX
• rlx,OKC,Mob

Sector Input

The NDFD is composed of files representing geographical areas called sectors and subsectors. There are seven supported sectors and 16 subsectors of the coterminus United States. The link below provides the input name for each sector/subsector. See the Coverage Map for the geographical area covered by each subsector. The geographical extent of other sectors can be seen on the NDFD Spatial Reference System page.

Sector Identifiers

Sector identifiers are not case sensitive (i.e. they may be upper, lower, or mixed case). Several examples of sector input follow:

• crgrlake
• pacnwest,pacswest,ALASKA

State Name Input

Some users may want to know if the GRIB2 files necessary to cover one or more States have changed. The following table contains the State abbreviations used as input to the service.

State Identifiers

State abbreviations are not case sensitive (i.e. they may be upper, lower, or mixed case). Several examples of State input follow:

• TX
• VA,fl,Mi

Point Input

All latitude and longitude values provided as input or in the output RUGS document 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.

A point input consists of one or more latitude/longitude pairs separated by a comma. The latitude and longitude values are separated by a "^" symbol. Several examples of point input follow:

• 35.5^-97.4
• 35.00^-82.0,38.0^-77.0,35.5^-97.4

Only points falling on an NDFD grid are valid. Users can view the extent of each NDFD grid on the NDFD Spatial Reference System page.

Element Input

Users tell RUGS which NDFD element(s) they are interested in. Users provide RUGS one or more NDFD element identifiers in a comma delimited list. Users can find valid NDFD element identifiers at the following link:

NDFD Element Identifiers

Element names are not case sensitive (i.e. they may be upper, lower, or mixed case). Several examples of State input follow:

• maxt
• mint,QPF,Td

Search Issuance Time Input

Users tell RUGS when they last searched for updates. This time tells RUGS to look for grids that were issued after the "issuanceSearchTime" time. Search times are Universal Coordinated Time (UTC) and are formatted according to the pattern: YYYY-MM-DDTHH:MM:SS (e.g. 2008-12-25T06:00:00).

Search Valid Time Input

Users tell RUGS which range of valid times to looks at within updated files. For example, if a User only wants updates for day 3 of the forecast, the user configures the searchStartTime and searchEndTime search times to bracket that time period. Using a searchStartTime time before the current time is equivilant to using the currrent time. Search times are Universal Coordinated Time (UTC) and are formatted according to the pattern: YYYY-MM-DDTHH:MM:SS (e.g. 2008-12-25T06:00:00).

Show Changed Valid Time Input

If users want to know which specific valid times changed in a recently update GRIB2 files, they set the showChangedTime input to "yes". If they do not want the modified valid times included in the response, they set showChangedTime to "no".