NetCDF Subset Service Reference (TDS 4.3)

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

Overview

The NetCDF Subset Service is a web service for subsetting CDM scientific datasets. The subsetting is specified using earth coordinates, such as lat/lon or projection coordinates bounding boxes and date ranges, rather than index ranges that refer to the underlying data arrays. The data arrays are subsetted but not resampled or reprojected, and preserve the resolution and accuracy of the original dataset.

A Dataset is described by a Dataset Description XML document, which describes the dataset in enough detail to enable a programmatic client to form valid data requests.

The NetCDF Subset Service may return netCDF binary files (using CF-1.0 when possible), XML, or ASCII, depending on the request and the dataset.

The NetCDF Subset Service uses HTTP GET with key-value pairs (KVP). The service interface tries to follow REST design, as well as Google/KML and W3C XML Schema Datatypes when applicable.

Currently the service support two kinds of subsetting requests: grid requests and grid as point requests. Default is grid request and if no bounding box or point is provided in the request the whole grid is returned in the response. If a point is specified with the parameters latitude and longitude the request will be a grid as point request and point features are extracted from the grid.

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.

Grid Dataset

A Grid Dataset is a collection of Grids which have horizontal (x,y) coordinates, and optional vertical and time coordinates. Grid data points next to each other in index space are next to each other in coordinate space.

Example gridDataset document (offline example)

Subsetting Parameters (summary)

Parameter Name	Required	Constraints	Description / possible values	default
var	yes	Variables must be in the dataset description.Only requests on variables with same vertical levels are supported	Name of variables, separated by ',' (comma).
latitude	no	Must be within the data(). If latitude is provided longitude must be provided too().	In Grid As Point requests latitude of the point.
longitude	no	Must be within the data(*). If longitude is provided latitude must be provided too.	In Grid As Point requests latitude of the point
north	no	lat/lon bounding box must have north > south	Used to define a lat/lon bounding box.Lat/lon bounding box must have all 4 parameters: north, south, east and west	If no bounding box is specified returns the whole grid
south	no	lat/lon bounding box must have north > south	Used to define a lat/lon bounding box.Lat/lon bounding box must have all 4 parameters: north, south, east and west	If no bounding box is specified returns the whole grid
east	no	lat/lon bounding box must have east > west; if crossing 180 meridian, use east boundary > 180	Used to define a lat/lon bounding box.Lat/lon bounding box must have all 4 parameters: north, south, east and west	If no bounding box is specified returns the whole grid
west	no	lat/lon bounding box must have east > west; if crossing 180 meridian, use east boundary > 180	Used to define a lat/lon bounding box.Lat/lon bounding box must have all 4 parameters: north, south, east and west	If no bounding box is specified returns the whole grid
minx	no	projection bounding box must have minx < maxx	Used to define a projection bounding box. Projection bounding box must have all 4 parameters: minx, miny, maxx, maxy	If no bounding box is specified returns the whole grid
maxx	no	projection bounding box must have minx < maxx	Used to define a projection bounding box. Projection bounding box must have all 4 parameters: minx, miny, maxx, maxy	If no bounding box is specified returns the whole grid
miny	no	projection bounding box must have miny < maxy	Used to define a projection bounding box. Projection bounding box must have all 4 parameters: minx, miny, maxx, maxy	If no bounding box is specified returns the whole grid
maxy	no	projection bounding box must have miny < maxy	Used to define a projection bounding box. Projection bounding box must have all 4 parameters: minx, miny, maxx, maxy	If no bounding box is specified returns the whole grid
time	no	Must be a time within the dataset time range	Time as a W3C date or "present". The time slice closest to the requested time is returned	If no time or time range is provided returns the closest to the current time
time_start	no	The provided time range must intersect the dataset time range	Used to specify the starting time of a time range. Time as a W3C date or "present". Two of time_start, time_end, time_duration must be present to define a valid time range.	If no time or time range is provided returns the closest to the current time
time_end	no	The provided time range must intersect the dataset time range	Used to specify the ending time of a time range. Time as a W3C date or "present". Two of time_start, time_end, time_duration must be present to define a valid time range.	If no time or time range is provided returns the closest to the current time
time_duration	no	The provided time range must intersect the dataset time range	Used to specify the time duration of a time range. Duration as a W3C time duration. Two of time_start, time_end, time_duration must be present to define a valid time range.	If no time or time range is provided returns the closest to the current time
temporal	no	Must be equal to "all" to have effect	Shorthand to request all the available time range	If no time or time range is provided returns the closest to the current time
timeStride	no	Only for grid requests	Take only every nth time in the available series	1
horStride	no	Only for grid requests	Take only every nth point (both x and y)	1
vertCoord	no	Requested variables must have the same vertical levels.		If the requested variables have vertical levels, all the vertical levels will be returned
accept	no	Accepted values for grid request are netCDF and for grid as point requests csv, xml, netCDF	Used to specify the returned format. Supported formats are netCDF for grid requests and csv, xml and netcdf for grid as point	Grid requests netcdf, Grid as point requests csv
(*)Note the lat/lon bounding box declared in the dataset description is an approximated rectangle to the actual lat/lon boundaries so there may be valid points within the data but ouside of the declared bounding box in the dataset description.

Subsetting types and use cases

Spatial and coordinate subsetting

We can provide two types of bounding boxes to subset the data:

Lat/lon bounding box: is specified with the params north, south, east and west. These parameters are spatial coordinates. 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. They define a rectangle and the data contained in the intersection of this rectangle with the data is returned.
Projection bounding box: is specified with the params minx, miny, maxx and maxy. Those parameters are coodinates on the projection of the data and also define the rectangle that will be returned.

The boundaries or the extension of the data can be checked in the dataset descriptions in the tags LatLonBox and projectionBox. Note that the declared LatLonBox is an approximated rectangle to the full extension of the data and there may be points outside of the declared LatLonBox but within the data. So the provided lat/lon bounding box does not necesarily have to intersect it but it has to intersect the actual data.

By default, if no spatial subsetting is specified the service returns the whole grid

Grid requests return a nectCDF binary file

Examples of query strings for spatial and coordinate subsetting:

Lat/lon bounding box: north=17.3&south=12.088&west=140.2&east=160.0
Projection bounding box: minx=-500&miny=-1600&maxx=500&maxy=0

Grid as point requests

The NetDFC Subset Service allows the user to extract data for a single point. This is done specifying the latitude and longitude for our point of interest. When these parameters are provided the service will extract point features types from the grid.

Grid as point requests support netCDF, csv and xml as format result for a request.

Examples:

latitude=17.3&longitude=140.2

Temporal subsetting and valid time ranges

There are several ways to do temporal subsetting requests:

Default:if no temporal subseting is specified the closest time to the current time is returned
All time range:A shorthand to request all the time range in a dataset is setting the parameter temporal=all. This can also be done providing a valid temporal range containing all the dataset time range
One single time:Passing the parameter time we will get the sime slice closest to the requested time if it is within the time range of the dataset
Valid time range:A valid time range is defined with two of the three parameters: time_start, time_end and time_duration

Times (time, time_start and time_end) must be specified as W3C date string or "present" and time_duration as a W3C time duration

Examples of time query strings with valid temporal ranges:

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)
time=2007-03-29T12:00:00Z
time=present

Vertical coordinate subsetting

Subset on the vertical axis of a variable or variables with the same vertical levels may be done with the vertCoord parameter.

By default, all vertical levels are returned.

Single Variable requests

Note that these single variable requests can be easily extended to multivariable request by simply passing a comma separated list of variables in the var= parameter. Please note that only requests on variables with same vertical levels are supported

var	Spatial subset	Horizontal Stride	Time range	Vertical Coordinate	Query string
Request: "Give me all of the data for the variable Temperature_pressure for the closest time to the current time"
Temperature_pressure					?var=Temperature_pressure
Request: "Give me all of the data for the variable Temperature_pressure for all the available time range in the dataset"
Temperature_pressure			temporal=all		?var=Temperature_pressure&temporal=all
Request: "Give me all of the data for the variable Temperature_pressure available in a given time range"
Temperature_pressure			time_start=YYYY-MM-DDThh:mm:ss.sTZD time_end=YYYY-MM-DDThh:mm:ss.sTZD (Using full temporal bounds)		?var=Temperature_pressure&time_start=YYYY-MM-DDThh:mm:ss.sTZD&time_end=YYYY-MM-DDThh:mm:ss.sTZD
Request: "Give me all of the data for the variable Temperature_pressure for a specific time"
Temperature_pressure			time=YYYY-MM-DDThh:mm:ss.sTZD		?var=Temperature_pressure&time=YYYY-MM-DDThh:mm:ss.sTZD
Request: "Give me the data for the variable Temperature_pressure over a given lat/lon bouding box for a specific time"
Temperature_pressure	north=41 west=-109.05 east==102.05 south=37		time=YYYY-MM-DDThh:mm:ss.sTZD		?var=Temperature_pressure&time=YYYY-MM-DDThh:mm:ss.sTZD&north=41&west=-109.05&east=-102.05&south=37
Request: "Give me variable Temperature_pressure for every 5th point on the grid (deltax=deltay=5)"
Temperature_pressure		5			?var=Temperature_pressure&horStride=5
Request: "Give me variable Temperature_pressure for every 5th point on the grid (deltax=deltay=5) over a given lat/lon bounding box"
Temperature_pressure	north=41 west=-109.05 east==102.05 south=37	5			?var=Temperature_pressure&north=41&west=-109.05&east=-102.05&south=37&horStride=5
Request: "Give me variable Temperature_pressure at a particular vertical level: 1000 mb"*
Temperature_pressure				1000	?var=Temperature_pressure&vertCoord=1000
* note that the vertical level value must be in the same units used in the dataset - in this example we assume millibars but you will need to check the dataset description to be sure.

Reference

W3C Time Duration

The lexical representation for duration is the[ISO 8601] extended format PnYn MnDTnH nMnS, where nY represents the number of years, nM the number of months, nD the number of days, 'T' is the date/time separator, nH the number of hours, nM the number of minutes and nS the number of seconds. The number of seconds can include decimal digits to arbitrary precision.

The values of the Year, Month, Day, Hour and Minutes components are not restricted but allow an arbitrary unsigned integer, i.e., an integer that conforms to the pattern [0-9]+.. Similarly, the value of the Seconds component allows an arbitrary unsigned decimal. Following [ISO 8601], at least one digit must follow the decimal point if it appears. That is, the value of the Seconds component must conform to the pattern [0-9]+(\.[0-9]+)?. Thus, the lexical representation of duration does not follow the alternative format of § 5.5.3.2.1 of [ISO 8601].

An optional preceding minus sign ('-') is allowed, to indicate a negative duration. If the sign is omitted a positive duration is indicated. See also ISO 8601 Date and Time Formats (§D).

For example, to indicate a duration of 1 year, 2 months, 3 days, 10 hours, and 30 minutes, one would write: P1Y2M3DT10H30M. One could also indicate a duration of minus 120 days as: -P120D.

Reduced precision and truncated representations of this format are allowed provided they conform to the following:

If the number of years, months, days, hours, minutes, or seconds in any expression equals zero, the number and its corresponding designator ·may· be omitted. However, at least one number and its designator ·must· be present.
The seconds part ·may· have a decimal fraction.
The designator 'T' must be absent if and only if all of the time items are absent. The designator 'P' must always be present.

For example, P1347Y, P1347M and P1Y2MT2H are all allowed; P0Y1347M and P0Y1347M0D are allowed. P-1347M is not allowed although -P1347M is allowed. P1Y2MT is not allowed.

See XML Schema duration for full details.

W3C Dates

For our purposes, and ISO Date can be a dateTime or a date:

A dateTime has the form: '-'? yyyy '-' mm '-' dd 'T' hh ':' mm ':' ss ('.' s+)? (zzzzzz)?

where

'-'? yyyy is a four-or-more digit optionally negative-signed numeral that represents the year; if more than four digits, leading zeros are prohibited, and '0000' is prohibited (see the Note above (§3.2.7); also note that a plus sign is not permitted);
the remaining '-'s are separators between parts of the date portion;
the first mm is a two-digit numeral that represents the month;
dd is a two-digit numeral that represents the day;
'T' is a separator indicating that time-of-day follows;
hh is a two-digit numeral that represents the hour; '24' is permitted if the minutes and seconds represented are zero, and the dateTime value so represented is the first instant of the following day (the hour property of a dateTime object in the ·value space· cannot have a value greater than 23);
':' is a separator between parts of the time-of-day portion;
the second mm is a two-digit numeral that represents the minute;
ss is a two-integer-digit numeral that represents the whole seconds;
'.' s+ (if present) represents the fractional seconds;
zzzzzz (if present) represents the time zone (as described below).

For example, 2002-10-10T12:00:00-05:00 (noon on 10 October 2002, Central Daylight Savings Time as well as Eastern Standard Time in the U.S.) is 2002-10-10T17:00:00Z, five hours later than 2002-10-10T12:00:00Z.

A date is the same as a dateTime without the time part : '-'? yyyy '-' mm '-' dd zzzzzz?

See XML Schema dateTime and date for full details

This document is maintained by Marcos Hermida and was last updated May, 2012

Unidata