Documentation

Using griddap to Request Data and Graphs from Gridded Datasets

griddap lets you request gridded data (for example, environmental data from satellites) and graphs of gridded data, via specially formed URLs.
The URLs specify everything: the dataset, the desired file type for the response, and the subset of data that you want to receive.
You can form these URLs by hand or with a computer program,
or (much easier) you can use the dataset's "Data Access Form" (oriented to requests for data)
or the dataset's "Make A Graph" form (oriented to requests for graphs and maps),
both of which generate the URL when the form is submitted.
griddap is a superset of the OPeNDAP DAP hyperslab protocol.

griddap request URLs must be in the form
http://coastwatch.pfeg.noaa.gov/erddap/griddap/ datasetID fileType {?query}
For example,
http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[(2007-10-21T00:00:00)][0][(-75):100:(75)][(180):100:(360)]

Details:

Requests must not have any internal spaces.
Requests are case sensitive.
{} is notation to denote an optional part of the request.
datasetID identifies the name that ERDDAP assigned to the dataset (for example, "erdBAssta5day").
You can see a list of datasetID options available via griddap.

fileType specifies the type of grid data file that you want to download (for example, ".htmlTable").
The actual extension of the resulting file may be slightly different than the fileType (for example, ".smallPdf" returns a small .pdf file).
The fileType options for downloading gridded data are:

Data fileTypes	Description	Info	Example
.asc	View the data as OPeNDAP-style comma-separated ASCII text.	info	example
.csv	Download the data as comma-separated ASCII text table (missing value = 'NaN'; times are ISO 8601 strings).	info	example
.das	View the data's metadata via an OPeNDAP Dataset Attribute Structure (DAS).	info	example
.dds	View the data's structure via an OPeNDAP Dataset Descriptor Structure (DDS).	info	example
.dods	OPeNDAP clients use this to download the data in the DODS binary format.	info	example
.esriAscii	Download an ESRI ASCII file (for lat lon data only; lon values can't be below and above 180).	info	example
.graph	View a Make A Graph web page.	info	example
.html	View an OPeNDAP-style HTML data access form.	info	example
.htmlTable	View an HTML file with the data in a table (times are ISO 8601 strings).	info	example
.json	View the data as a JSON table (missing value = 'null'; times are ISO 8601 strings).	info	example
.mat	Download a MATLAB binary file.	info	example
.nc	Download a NetCDF binary file with COARDS/CF/THREDDS metadata.	info	example
.ncHeader	View the header (the metadata) for the NetCDF file.	info	example
.tsv	Download the data as tab-separated ASCII text table (missing value = 'NaN'; times are ISO 8601 strings).	info	example
.xhtml	View an XHTML file with the data in a table (times are ISO 8601 strings).	info	example

For example, here is a request to download data:
http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[(2007-10-21T00:00:00)][0][(-75):100:(75)][(180):100:(360)]

MATLAB
MATLAB users can download data from within MATLAB. Here is a one line example:

load(urlwrite('http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.mat?sst[(2007-10-21)][0][(-75):50:(75)][(180):50:(360)]&.draw=surface&.vars=longitude|latitude|sst&.colorBar=Rainbow|C|Linear|0|32|', 'test.mat'));

The data will be in a MATLAB structure. The structure's name will be the datasetID (for example, "erdBAssta5day").
The structure's internal variables will have the same names as in ERDDAP (for example, use "fieldnames(erdBAssta5day)" ).
If you download a 2D matrix of data (as in the example above), you can plot it with (for example):

imagesc(erdBAssta5day.longitude, erdBAssta5day.latitude, squeeze(erdBAssta5day.sst), [0 32])
set(gca, 'YDir', 'normal')

The numbers at the end of the first line specify the range for the color mapping. The 'set' command flips the map to make it upright.

Making an Image with a Graph or Map of Gridded Data
If a griddap request URL specifies a subset of data which is suitable for making a graph or a map,
and the fileType is an image fileType, griddap will return an image with a graph or map.
griddap request URLs can include optional graphics commands which let you customize the graph or map.
As with other griddap request URLs, you can create these URLs by hand or have a computer program do it.
Or, you can use the Make A Graph web pages, which simplify creating these URLs (see the "graph" links in the table of griddap datasets).

The fileType options for downloading images of graphs and maps of grid data are:

Image fileTypes	Description	Info	Example
.geotif	Download a georeferenced .tif (GeoTIFF) image file (for lat lon data only; lon values can't be below and above 180).	info	example
.kml	Download a Google Earth .kml file (for lat, lon, [time] results only)	info	example
.smallPdf	Download a small .pdf image file with a graph/map of the data you selected.	info	example
.pdf	Download a standard, medium-sized, .pdf image file with a graph/map of the data you selected.	info	example
.largePdf	Download a large .pdf image file with a graph/map of the data you selected.	info	example
.smallPng	Download a small .png image file with a map of the data you selected.	info	example
.png	Download a standard, medium-sized .png image file with a map of the data you selected.	info	example
.largePng	Download a large .png image file with a map of the data you selected.	info	example
.transparentPng	Download a .png image file with the data you selected (a geographic map without axes, landmask, or legend).	info	example

query is the part of the request after the "?". It specifies the subset of data that you want to receive.
In griddap, it is an optional OPeNDAP DAP-style hyperslab query which can request:
- One or more dimension (axis) variables, for example
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?latitude[0:10:100] .
- One or more data variables, for example
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[656][0][0:100:1500][1800:100:3600] .
  To request more than one data variable, separate the desired data variable names by commas.
  If you do request more than one data variable, the requested subset for each variable must be identical (see below).
  (In griddap, all data variables within a grid dataset share the same dimensions.)
- The entire dataset. Omitting the entire query is the same as requesting all of the data for all of the variables.
  Because of the large size of most datasets, this is usually only appropriate for fileTypes that don't return actual data values (e.g., .das, .dds, and .html). For example,
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.dds
  griddap is designed to handle requests of any size but trying to download all of the data with one request will usually fail (for example, downloads that last days usually fail at some point).
  If you need all of the data, consider breaking your big request into several smaller requests.
  If you just need a sample of the data, use the largest acceptable stride values (see below).
Using [start:stride:stop]
When requesting dimension (axis) variables or data variables, the query may specify a subset of a given dimension by identifying the [start{{:stride}:stop}] indices for that dimension.
- start is the index of the first desired value. Indices are 0-based. (0 is the first index. 1 is the second index. ...)
  ERDDAP extends the DAP standard: ERDDAP will interpret last as the last available index value.
- stop is the index of the last desired value.
  ERDDAP extends the DAP standard: ERDDAP will interpret last as the last available index value.
- stride indicates how many intervening values to get: 1=get every value, 2=get every other value, 3=get every third value, ...
  Stride values are in index units (not the units of the dimension).
- Specifying only two values for a dimension (i.e., [start:stop]) is interpreted as [start:1:stop].
- Specifying only one value for a dimension (i.e., [start]) is interpreted as [start:1:start].
- Specifying no values for a dimension (i.e., []) is interpreted as [0:1:max].
- Omitting all of the [start:stride:stop] values (that is, requesting the variable without the subset constraint) is equivalent to requesting the entire variable.
  For dimension variables (for example, longitude, latitude, and time) and for fileTypes that don't download actual data (notably, .das, .dds, .html, and all of the graph and map fileTypes) this is fine. For example,
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.dds?sst
  For other fileTypes (for example, .csv, .mat, .nc, .tsv), the resulting data may be very large.
  griddap is designed to handle requests of any size. But if you try to download all of the data with one request, the request will often fail for other reasons (for example, downloads that last for days usually fail at some point).
  If you need all of the data, consider breaking your big request into several smaller requests.
  If you just need a sample of the data, use the largest acceptable stride values.
- griddap extends the standard DAP subset syntax by allowing the start and/or stop values to be actual dimension values (for example, longitude values in degrees_east) within parentheses, instead of array indices.
  This example with [time][altitude][latitude][longitude] dimension values
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[(1192924800)][0][(-75):100:(75)][(180):100:(360)]
  is (at least at the time of writing this) equivalent to this example with dimension indices
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[656][0][0:100:1500][1800:100:3600]
  The value in parentheses must be within the range of values for the dimension.
  If the value in parentheses doesn't exactly equal one of the dimension values, the closest dimension value will be used.
- griddap does not allow parentheses around stride values. The reasoning is...
  With the start and stop values, it is easy to convert the value in parentheses into the appropriate index value
  by finding the nearest dimension value. This works if the dimension values are evenly spaced or not.
  If the dimension values were always evenly spaced, it would be easy to use a similar technique to convert a stride
  value in parentheses into a stride index value. But dimension values often aren't evenly spaced.
  So for now, ERDDAP doesn't support the parentheses notation for stride values.
- griddap always stores date/time values as numeric values in seconds since 1970-01-01T00:00:00Z.
  Here is an example of a query which includes date/time numeric values:
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[(1192924800)][0][(-75):100:(75)][(180):100:(360)]
  Some fileTypes (notably, .csv, .tsv, .htmlTable, and .xhtml) display date/time values as ISO 8601:2004 "extended" date/time strings (e.g., 2002-08-03T12:30:00Z).
- For the time dimension, griddap extends the DAP standard by allowing you to specify an ISO 8601 date/time values in parentheses, which griddap then converts to the internal numeric value (in seconds since 1970-01-01T00:00:00Z) and then to the appropriate array index.
  The ISO date/time value should be in the form: YYYY-MM-DDThh:mm:ssZ, where Z is 'Z' or a ±hh:mm offset from UTC.
  If you omit Z (or the ±hh:mm offset), :ssZ, :mm:ssZ, or Thh:mm:ssZ from the ISO date/time that you specify, the missing fields are assumed to be 0.
  The example below is equivalent (at least at the time of writing this) to the examples above:
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[(2007-10-21T00:00:00)][0][(-75):100:(75)][(180):100:(360)]
- Graphics Commands - griddap extends the DAP standard by allowing graphics commands in the query.
  The Make A Graph web pages simplify the creation of URLs with these graphics commands (see the "graph" links in the table of griddap datasets).
  So we recommend using the Make A Graph web pages to generate URLs, and then, when needed, using the information here to modify the URLs for special purposes.
  These commands are optional. If present, they must occur after the data request part of the query.
  These commands are used by griddap if you request an image fileType (e.g., .png) and are ignored if you request a data file (e.g., .asc).
  If relevant commands are not included in your request, griddap uses the defaults and tries its best to generate a reasonable graph or map.
  All of the commands are in the form &.commandName=value .
  If the value has sub-values, they are separated by the '|' character.
  In most cases, sub-values can be omitted, causing the default value to be used.
  In most cases, if sub-values are omitted from the end of the list, you can just truncate the list (for example, "a||c" can be used instead of "a||c||||").
  The commands are:
  - &.colorBar= specifies the settings for a color bar. The sub-values are:
    - palette - see a Make A Graph web page for options (e.g., "Rainbow").
      The default varies based on min and max: if -1*min ~= max, the default is "BlueWhiteRed";
      otherwise, the default is "Rainbow".
    - continuous - must be either no value (the default), 'C' (for Continuous), or 'D' (for Discrete). The default is different for different datasets.
    - scale - must be either no value (the default), "Linear", or "Log". The default is different for different datasets.
    - min - The minimum value for the color bar. The default is different for different datasets.
    - max - The maximum value for the color bar. The default is different for different datasets.
    - nSections - The preferred number of sections (for Log color bars, this is a minimum value). The default is different for different datasets.
  - &.color= specifies the color for lines, markers, vectors, etc. The value must be specified as an 0xRRGGBB value (e.g., 0xFF0000 is red, 0x00FF00 is green). The default is 0x000000 (black).
  - &.draw= specifies how the data will be drawn, as "lines", "linesAndMarkers", "markers", "sticks", "surface", or "vectors".
  - &.font= specifies a scale factor for the font (e.g., 1.5 would make the font 1.5 times as big as normal).
  - &.land= specifies whether the land should be drawn "under" or "over" (the default) the data.
    Terrestrial researchers usually prefer "under". Oceanographers often prefer "over".
  - &.marker= specifies markerType|markerSize .
    markerType is an integer: 0=None, 1=Plus, 2=X, 3=Dot, 4=Square, 5=Filled Square (default), 6=Circle, 7=Filled Circle, 8=Up Triangle, 9=Filled Up Triangle.
    markerSize is an integer from 3 to 50 (default=5)
  - &.vars= is a '|'-separated list of variables names. Defaults are hard to predict.
    The meaning associated with each position varies with the &.draw value:
    - for lines: xAxis|yAxis
    - for linesAndMarkers: xAxis|yAxis|Color
    - for markers: xAxis|yAxis|Color
    - for sticks: xAxis|uComponent|vComponent
    - for surface: xAxis|yAxis|Color
    - for vectors: xAxis|yAxis|uComponent|vComponent
    If xAxis=longitude and yAxis=latitude, you get a map; otherwise, you get a graph.
  - &.vec= specifies the data vector length (in data units) to be scaled to the size of the sample vector in the legend. The default varies based on the data.
  - &.xRange= specifies the min|max for the X axis. The default varies based on the data.
  - &.yRange= specifies the min|max for the Y axis. The default varies based on the data.
  A sample graph URL is
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.png?sst[(2007-07-01):(2007-10-21)][0][(29)][(225)]&.draw=linesAndMarkers&.vars=time|sst|&.marker=1|3&.color=0xFF9900&.colorBar=|C|Linear|||
  Or, if you change the fileType in the URL from .png to .graph, you can see a Make A Graph web page with that request loaded:
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.graph?sst[(2007-07-01):(2007-10-21)][0][(29)][(225)]&.draw=linesAndMarkers&.vars=time|sst|&.marker=1|3&.color=0xFF9900&.colorBar=|C|Linear|||
  That makes it easy for humans to modify an image request to make a similar graph or map.
  Or, if you change the fileType in the URL from .png to a data fileType (e.g., .htmlTable), you can download the data that was graphed:
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[(2007-07-01):(2007-10-21)][0][(29)][(225)]&.draw=linesAndMarkers&.vars=time|sst|&.marker=1|3&.color=0xFF9900&.colorBar=|C|Linear|||
  A sample map URL is
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.png?sst[(2007-10-21)][0][(-75):50:(75)][(180):50:(360)]&.draw=surface&.vars=longitude|latitude|sst&.colorBar=Rainbow|C|Linear|0|32|
  Or, if you change the fileType in the URL from .png to .graph, you can see a Make A Graph web page with that request loaded:
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.graph?sst[(2007-10-21)][0][(-75):50:(75)][(180):50:(360)]&.draw=surface&.vars=longitude|latitude|sst&.colorBar=Rainbow|C|Linear|0|32|
  Or, if you change the fileType in the URL from .png to a data fileType (e.g., .htmlTable), you can download the data that was mapped:
  http://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.htmlTable?sst[(2007-10-21)][0][(-75):50:(75)][(180):50:(360)]&.draw=surface&.vars=longitude|latitude|sst&.colorBar=Rainbow|C|Linear|0|32|

Other Information

Data Model - Each griddap dataset can be represented as:
- An ordered list of one or more 1-dimensional axis variables.
  Each axis variable has data of one specific type.
  The supported types are int8, uint16, int16, int32, int64, float32, and float64.
  Missing values are not allowed.
  The values MUST be sorted (in ascending (recommended) or descending order). Unsorted is not allowed.
  Each axis variable has a name composed of a letter (A-Z, a-z) and then 0 or more characters (A-Z, a-z, 0-9, _).
  Each axis variable has a set of metadata expressed as Key=Value pairs.
- A set of one or more n-dimensional data variables.
  All data variables use all of the axis variables, in order, as their dimensions.
  Each data variable has data of one specific type.
  The supported types are (int8, uint16, int16, int32, int64, float32, float64, String of any length).
  Missing values are allowed.
  Each data variable has a name composed of a letter (A-Z, a-z) and then 0 or more characters (A-Z, a-z, 0-9, _).
  Each data variable has a set of metadata expressed as Key=Value pairs.
- Global metadata expressed as Key=Value pairs.
  Each metadata value is either one or more numeric values (of one type), or one or more Strings
  of any length (using \n as the separator).
Special Variables
- In griddap, a longitude axis variable (if present) always has the name "longitude" and the units "degrees_east".
- In griddap, a latitude axis variable (if present) always has the name "latitude" and the units "degrees_north".
- In griddap, an altitude axis variable (if present) always has the name "altitude" and the units "m" above sea level. Locations below sea level have negative altitude values.
- In griddap, a time axis variable (if present) always has the name "time" and the units "seconds since 1970-01-01T00:00:00Z".
Incompatibilities
- File Types - Some results file types have restrictions.
  For example, .kml is only appropriate for results with longitude and latitude values.
  If a given request is incompatible with the requested file type, griddap throws an error.
Requesting Compressed Files
ERDDAP doesn't offer results stored in compressed (e.g., .zip or .gzip) files.
Instead, ERDDAP looks for accept-encoding in the HTTP GET request header sent by the client.
If a supported compression type ("gzip", "x-gzip", or "deflate") is found in the accept-encoding list,
ERDDAP includes "content-encoding" in the HTTP response header and compresses the data as it transmits it.
It is up to the client program to look for "content-encoding" and decompress the data.
Browsers and OPeNDAP clients do this by default. They request compressed data and decompress the returned data automatically.
Other clients (e.g., Java programs) have to do this explicitly.

ERDDAP Version 1.12

Questions, comments, suggestions? Contact bob dot simons at noaa dot gov.
ERDDAP is a brought to you by NOAA NMFS SFSC ERD.
Disclaimers | Privacy Policy
Usage Limitations - The SeaWiFS images and data from this site may be used for free, but not redistributed;
all other images and data from this site may be used and redistributed for free.