NEXRAD Web Service

I. Overview
This page documents the specifications of the various web methods offered by the NEXRAD web service and how web clients should interact with it. The address for the service is: http://nexrad.tacc.utexas.edu/nexradws/xmrgWebService.asmx. This is the URL to use for adding the web reference.

WSDL service description is available here.

Sample clients are available. They are written in VS.NET (C#) and Eclipse (Java). The .NET client offers a GUI, while the Java client is a console application. Currently, the Java client is not able to make asynchronous calls. For the .NET client, you will need WSE 3.0, which can be found here:
II. Description of Web Methods
There are currently seven web methods on the web service.

The two methods xmrgAreaMapAccessDbHRAP(..) and xmrgAreaMapAccessDbLonLat(..) will create an Access database on the server, taking HRAP and longitude-latitude input respectively. The columns in the created databases are in ArcHydro format: OBJECTID, FeatureID, TSTypeID, TSDateTime, TSValue. Object ID is the unique key for the row and may be seeded as any integer value (see method details in Table 1).

Alternatively, there are two other methods xmrgAreaMapASCIIHRAP(..) and xmrgAreaMapASCIILonLat(..) that will store the NEXRAD data into a text file. Each string in the array will be delimited by commas (,) and follow ArcHydro format: FeatureID, TSTypeID, TSDateTime, TSValue.

Whether requesting data in database or text file form, the files are all zipped. Furthermore, all requests should be asynchronous due to the lengthy processing time for large collections of data. In .NET, this is done by simply adding "ASync" to the end of a method name when you call it. For example, xmrgAreaMapASCIIHRAPAsync(..).

The user will receive two emails after sending a request: (1) confirming that the request was received, and (2) either a confirmation that the request is ready, or a description of an error if one occurred.

For file transfer, two other methods GetFileSize(..) and DownloadChunk(..) can be used to download the file from the server; note that the file should be downloaded in parts and not all at once (see sample code). Alternatively, the files can be downloaded through a web browser in the path specified in the confirmation email.

The last method ConvertToHRAP(..) is for utility purposes; it handles the conversion of longitude-latitude coordinates (in decimal degrees) to HRAP coordinates.

III. Specification of Web Methods

Table 1. Method and Parameter Specification
public bool xmrgAreaMapASCIIHRAP(string FileName, string TimeStartStr, string TimeStopStr, int x1, int y1, int x2, int y2, string email)
Creates a text file of NEXRAD data on the server. Returns true if successful, false otherwise, given:
string FileName – desired filename for the text file. DO NOT add file extensions.
string TimeStartStr – string input of starting time, able to be parsed into DateTime format.
string TimeStopStr – string input of ending time, able to be parsed into DateTime format.
int x1, y1, x2, y2 – HRAP coordinates forming a box, in which (x1,y1) is the TOP-LEFT corner and (x2,y2) is the LOWER-RIGHT corner. Make sure x2 > x1 and y2 > y1.
string email – email address to notify when the data is ready.

public bool xmrgAreaMapASCIILonLat(string FileName, string TimeStartStr, string TimeStopStr, double lon1, double lat1, double lon2, double lat2, string email)
Creates a text file of NEXRAD data on the server. Returns true if successful, false otherwise, given:
string FileName – desired filename for the text file. DO NOT add file extensions.
string TimeStartStr – string input of starting time, able to be parsed into DateTime format.
string TimeStopStr – string input of ending time, able to be parsed into DateTime format.
double lon1,lat1,lon2,lat2 – longitude-latitude coordinates (in decimal degrees) forming a box, in which (lon1,lat1) is the LOWER-LEFT corner and (lon2,lat2) is the TOP-RIGHT corner.
string email – email address to notify when the data is ready.

public bool xmrgAreaMapAccessDbHRAP(string FileName, string TimeStartStr, string TimeStopStr, int x1, int y1, int x2, int y2, int inputOID, string email)
Creates an Access database on the NEXRAD server. Returns true if Access database creation is successful, false otherwise, given:
string FileName – desired filename for the database. DO NOT add file extensions.
string TimeStartStr – string input of starting time, able to be parsed into DateTime format.
string TimeStopStr – string input of ending time, able to be parsed into DateTime format.
int x1, y1, x2, y2 – HRAP coordinates forming a box, in which (x1,y1) is the TOP-LEFT corner and (x2,y2) is the LOWER-RIGHT corner. Make sure x2 > x1 and y2 > y1.
string email – email address to notify when the data is ready.

public bool xmrgAreaMapAccessDbLonLat(string FileName, string TimeStartStr, string TimeStopStr, double lon1, double lat1, double lon2, double lat2, int inputOID, string email)
Creates an Access database on the NEXRAD server. Returns true if Access database creation is successful, false otherwise, given:
string FileName – desired filename for the database. DO NOT add file extensions.
string TimeStartStr – string input of starting time, able to be parsed into DateTime format.
string TimeStopStr – string input of ending time, able to be parsed into DateTime format.
double lon1,lat1,lon2,lat2 – longitude-latitude coordinates (in decimal degrees) forming a box, in which (lon1,lat1) is the LOWER-LEFT corner and (lon2,lat2) is the TOP-RIGHT corner.
string email – email address to notify when the data is ready.

public long GetFileSize(string FileName, bool type)
Returns file size in bytes, given:
string FileName – filename of the database; should be the same as the one in xmrgAreaMapAccessDb(..)
bool type - true for database (*.mdb) file, false for text (*.txt) file

public byte[] DownloadChunk(string FileName, long Offset, int BufferSize, bool type)
Returns an array of bytes of a specified file, given:
string FileName – filename of the database, should be the same as the one in xmrgAreaMapAccessDb(..)
long Offset – offset for which byte of the file to begin at
int BufferSize – size of the buffer, in bytes
bool type - true for database (*.mdb) file, false for text (*.txt) file

public int[] ConvertToHRAP(double lon, double lat)
Returns HRAP-X and HRAP-Y coordinates in an integer array, given:
double lon – longitude in decimal degrees; use negative values if western values
double lat – latitude in decimal degrees

IV. Making a Request
Basic outline of the request process. See client/source for coding details.
  1. Add this web reference to your client project:
    http://nexrad.tacc.utexas.edu/nexradws/xmrgWebService.asmx.
  2. Instantiate a web service object.
  3. Use the web service object to call one of the area map methods.
    (When calling the method, please choose a fairly UNIQUE filename. If the filename you enter has already been used, the web service will return an error.)
  4. Wait for email confirming completion of the database.
  5. Set up your client to download the database file. Alternatively, you may download the file(s) at the path specified on the confirmation email.
V. Sample Client Implementation
This section includes sample C# client code for an asynchronous request for an Access database. A request for the text file is done in a similar manner, just make sure to change the parameters in the necessary methods. The NEXRAD web service uses Message Transmission Optimization Mechanism (MTOM) for transmitting large amounts of data between the service and clients. One may need to configure their client for MTOM (WSE 3.0 documentation for .NET may be found at MSDN).

Much of the code is self-explanatory. Take note that the method DownloadChunk(..) returns parts of the specified file one at a time and requires several iterations to get the complete file. This is because even though the web service uses MTOM, files larger than 100MB still have difficulty transmitting.
Table 2. Sample C# Client Code
namespace Client
{
    cowgirl.xmrgWebService ws = new cowgirl.xmrgWebService();
    private string FileName = "testDatabase"; // note that there is no file extension
    private int ChunkSize = 64 * 1024; // 64KB
    private string TimeStart = "2000-01-01 00:00";
    private string TimeStop = "2000-12-31 23:00";
    private int x1 = 500;
    private int y1 = 500;
    private int x2 = 600;
    private int y2 = 600;
    private int OID = 100000000;
    private string email = "jdoe@gmail.com";
   

    // setup an event handler and make the asynchronous call
    void AsyncCall()
    {
       // set up event handler for when asynchronous call finishes (optional)
       ws.xmrgAreaMapAccessDbCompleted +=
          new global::Client.cowgirl.xmrgAreaMapAccessDbCompletedEventHandler(AsyncDone);
       // call the method
       ws.xmrgAreaMapAccessDbAsync(FileName, TimeStart, TimeStop, x1, y1, x2, y2, OID, email);
    }

    // automatically performs this function when asynchronous call returns,
    // if the client window is still open (this is entirely optional)
    private void AsyncDone(object sender, global::Client.cowgirl.xmrgAreaMapAccessDbCompletedEventArgs e)
    {
       // show windows messagebox, can do other things here too
       MessageBox.Show("Your data has been successfully completed. You may now download the data.");
    }

    void DownloadDatabase()
    {
       string SaveToPath = "C:\\downloads\\" + FileName;
       long FileSize;

       // try to get, fails if database is still building or does not exist
       try
       {
          FileSize = ws.GetFileSize(FileName, true); // remember that true == mdb download, false == txt download
       }
       catch
       {
          // failure, throw exception
       }

       // if file did not exist, then returns -1.
       if (FileSize == -1)
       {
          // throw exception
       }

       int numIterations = 0;
       long ReceivedBytes = 0;

       using (FileStream fs = new FileStream(SaveToPath, FileMode.Append, FileAccess.Write))
       {
          while (ReceivedBytes < FileSize)
          {
            try
            {
               // although this function returns a byte[], it is actually
               // sent using MTOM because of the configuration settings.
               byte[] Buffer = ws.DownloadChunk(FileName, ReceivedBytes, ChunkSize, true); // true == mdb download
               fs.Write(Buffer, 0, Buffer.Length);
               ReceivedBytes += Buffer.Length;
            }
            catch (Exception ex)
            {
               int NumRetries = 0;
               int MaxRetries = 5;
               if (NumRetries++ < MaxRetries)
               {
                  // swallow the exception and try again
               }
               else
               {
                  fs.Close();
                  // throw exception
               }
            }
            numIterations++;
          }
       }
    }