NetCDF Subset Service for Point Data (version 0.2)

Please note that the interface described here is still a prototype, and subject to change.

Please send comments to the THREDDS email group (preferred) or to John CaronOverview

See NetCDF Subset Service for an overview.

Metar Subset Service

We have a prototype service for IDD METAR data at http://motherlode.ucar.edu:8080/thredds/ncss/metars/dataset.html. Sample URLS look like:

• Current metar reading for station CAG, in XML fomat:
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=xml&stn=CAG&time=present
• All data in last 24 hours for station CAG, in CSV fomat:
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=csv&stn=CAG&time_end=present&time_duration=PT24H
• All available data at the station ACK, in raw format:
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=raw&stn=ACK
• Current metar reading from the station closest to lat, lon = (40, -105) in XML:
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=xml&latitude=40&longitude=-105&time=present
• All data within latitude [40,43] and longitude [-105, -103], in CSV format:
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=csv&south=40&west=-105&north=43&east=-103
• Only return the fields named wind_speed and wind_from_direction in XML:
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=xml&stn=JYG&var=wind_speed,wind_from_direction&time=present
• Get data in the last 12 hours, for a list of stations:
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=csv&stn=CAG,HDN,EGE&time_end=present&time_duration=PT12H
• Get latest data for all stations, return as netcCDF file
  • http://motherlode.ucar.edu:8080/thredds/ncss/metars?accept=netcdf&time=present

Other interesting URLs for the metar service:

• An HTML form for interactive input
• The dataset XML document (offline example)
• The station List XML document (offline example)
• Example netCDF file output in Unidata Station Observation format. (The file format uses double linked lists to associate the observations with the station.)

Subsetting Parameters

A. Specify variables

• var=name of variables, separated by ',' (comma).

The list of valid variables is available from the Dataset Description.

Examples:

• var=QCSurface
• var=QC,LZT,PQ
• var=T&var=Pressure&var=RH (allowed, but comma seperated names are preferred)

Variable names with spaces or other illegal characters must be escaped.

B. Specify spatial extent

Latitude, longitude values are specified in decimal degrees north and east, respectively.

Use one of the following methods:

1. Specify lat/lon bounding box

Specify all of these parameters (order does not matter):

• north: latitude north (decimal degrees)
• south: latitude south (decimal degrees)
• east: longitude east (decimal degrees)
• west: longitude west (decimal degrees)

The bounding box has west as its west edge, includes all points going east until the east edge. Units must be degrees east, may be positive or negative, and will be taken modulo 360. Therefore, when crossing the dateline, the west edge may be greater than the east edge. Examples:

• north=17.3&south=12.088&west=140.2&east=160.0

2. Specify lat/lon point

• latitude: latitude of point, decimal degrees north
• longitude: longitude of point, decimal degrees east

The requested point must lie within the dataset spatial range. The station closest to the requested point will be used.

Examples:

• latitude=17.3&longitude=140.2

3. Specify station(s)

You may specify a list of stations instead of the lat/lon point or bounding box

• stn=name of stations, separated by ',' (comma)

The list of valid stations is available from the Dataset Description. Station names with spaces or other illegal characters must be escaped.

Examples:

• stn=KDEN
• stn=KDEN,KPAL,SDOL
• stn=KDEN&stn=KPAL&stn=SDOL

C. Specify time

Use one of the following methods:

1. Time range

Specify 2 of these 3 parameters (order does not matter):

• time_start: starting time as an W3C date string or "present"
• time_end: ending time as an W3C date string or "present"
• time_duration: length of time as an W3C time duration

The intersection of the requested time range with the dataset time range will be returned.

Examples:

• time_start=2007-03-29T12:00:00Z&time_end=2007-03-29T13:00:00Z (between 12 and 1 pm Greenwich time)
• time_start=present&time_duration=P3D (get 3 day forecast starting from the present)
• time_end=present&time_duration=PT3H (get last 3 hours)

2. Time point

• time: time as an W3C date string or "present"

The requested time point must lie within the dataset time range. The time slice/point closest to the requested time will be returned.

Examples:

• time=2007-03-29T12:00:00Z
• time=present

D. Specify the return format

Specify the return format(s) that you want by using the accept parameter:

accept=mime_type[,mime-type][,mime-type]

The list of possible return formats varies depending on the dataset, and can be found in the Dataset Description Document. Your request specifies the list of acceptable types, if none are valid a 400 "Bad Request" HTTP status is returned. If you specify multiple mime-types, the server will choose one of them.

The server returns the actual return format in the Content-Type header, examples:

• Content-Type: text/plain;charset=ISO-8859-1
• Content-Type: application/x-netcdf

Query examples:

• accept=application/x-netcdf requests a netcdf file
• accept=netcdf requests a netcdf file
• accept=ascii,csv requests either an ascii or csv document back

The possible mime-types and aliases:

Mime Type	Synonyms
text/plain	raw, ascii
application/xml	xml
text/csv	csv
text/html	html
application/x-netcdf	netcdf

The list of actual return formats depends on the dataset, and can be found in the Dataset Description Document.

 

NetCDF File Writing Rules

• A valid NetCDF file is returned in Unidata Station Observation format.
• The specified variables(s) and their attributes are included.

Notes

• When writing raw format, the var parameter is ignored, and the entire text report is returned

 

Dataset Descriptions

Each dataset has an XML document called the Dataset Description Document. These are intended to perform the same function as OGC GetCapabilities or Atom Introspection, that is, provide clients with the necessary information to formulate a valid request and send it to the server. The content of these documents is still evolving.

Station Observation Dataset

A Station Observation Dataset is a collection of time series of observations at named locations called stations.

The dataset is described by a stationObsDataset document, which in turn points to the list of valid stations in a seperate stationCollection document. The stationCollection document can be quite large, and caching on the client (eg using the If-Modified-Since header) is an important optimization.

• Example stationObsDataset document (offline example)
• Example stationCollection document (offline example)