ERDDAP > griddap > Documentation

Using griddap to Request Data and Graphs from Gridded Datasets

griddap lets you request a data subset, graph, or map from a gridded dataset (for example, sea surface temperature data from a satellite), via a specially formed URL. griddap uses the OPeNDAP Data Access Protocol (DAP) and its projection constraints.

The URL specifies what you want: the dataset, a description of the graph or the subset of the data, and the file type for the response.

• (easy) You can get data by using the dataset's Data Access Form. It makes the URL for you.
• (easy) You can make a graph or map by using the dataset's Make A Graph form. It makes the URL for you.
• (not hard) You can bypass the forms and get the data or make a graph or map by generating the URL by hand or with a computer program or script.

griddap request URLs must be in the form
https://coastwatch.pfeg.noaa.gov/erddap/griddap/datasetID.fileType{?query}
For example,
https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]
Thus, the query is often a data variable name (e.g., analysed_sst), followed by [(start):stride:(stop)] (or a shorter variation of that) for each of the variable's dimensions (for example, [time][latitude][longitude]).

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, jplMURSST41). 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, .htmlTable returns an .html file).

  Which fileType should I use?
  It's entirely up to you. In general, pick the fileType which meets your needs and is easiest to use. You will use different fileTypes in different situations, e.g., viewing a graph in a browser (.png) vs. viewing the data in a browser (.htmlTable) vs. downloading a data file (e.g., .nc or .csv) vs. working with some software tool (e.g., .nc or .odv). If you are going to download lots of large files, you might also want to give some weight to fileTypes that are more compact and so can be downloaded faster.

  The fileType options for downloading gridded data are:
   

  Data fileTypes	Description	Info	Example
  .asc	View OPeNDAP-style ISO-8859-1 comma-separated text.	info	example
  .csv	Download a ISO-8859-1 comma-separated text table (line 1: names; line 2: units; ISO 8601 times).	info	example
  .csvp	Download a ISO-8859-1 .csv file with line 1: name (units). Times are ISO 8601 strings.	info	example
  .csv0	Download a ISO-8859-1 .csv file without column names or units. Times are ISO 8601 strings.	info	example
  .das	View the dataset's metadata via an ISO-8859-1 OPeNDAP Dataset Attribute Structure (DAS).	info	example
  .dds	View the dataset's structure via an ISO-8859-1 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 ISO-8859-1 ESRI ASCII file (latitude longitude data only; longitude must be all below or all above 180).	info	example
  .fgdc	View the dataset's UTF-8 FGDC .xml metadata.	info	example
  .graph	View a Make A Graph web page.	info	example
  .help	View a web page with a description of griddap.	info	example
  .html	View an OPeNDAP-style HTML Data Access Form.	info	example
  .htmlTable	View a UTF-8 .html web page with the data in a table. Times are ISO 8601 strings.	info	example
  .iso19115	View the dataset's ISO 19115-2/19139 UTF-8 .xml metadata.	info	example
  .itx	Download an ISO-8859-1 Igor Text File. Each axis variable and each data variable becomes a wave.	info	example
  .json	View a table-like UTF-8 JSON file (missing value = 'null'; times are ISO 8601 strings).	info	example
  .jsonlCSV1	View a UTF-8 JSON Lines CSV file with column names on line 1 (mv = 'null'; times are ISO 8601 strings).	info	example
  .jsonlCSV	View a UTF-8 JSON Lines CSV file without column names (mv = 'null'; times are ISO 8601 strings).	info	example
  .jsonlKVP	View a UTF-8 JSON Lines file with Key:Value pairs (missing value = 'null'; times are ISO 8601 strings).	info	example
  .mat	Download a MATLAB binary file.	info	example
  .nc	Download a NetCDF-3 binary file with COARDS/CF/ACDD metadata.	info	example
  .ncHeader	View the UTF-8 header (the metadata) for the NetCDF-3 .nc file.	info	example
  .ncml	View the dataset's structure and metadata as a UTF-8 NCML .xml file.	info	example
  .nccsv	Download a NetCDF-3-like 7-bit ASCII NCCSV .csv file with COARDS/CF/ACDD metadata.	info	example
  .nccsvMetadata	View the dataset's metadata as the top half of a 7-bit ASCII NCCSV .csv file.	info	example
  .ncoJson	Download a UTF-8 NCO lvl=2 JSON file with COARDS/CF/ACDD metadata.	info	example
  .odvTxt	Download time,latitude,longitude,otherVariables as an ODV Generic Spreadsheet File (.txt).	info	example
  .timeGaps	View a UTF-8 list of gaps in the time values which are larger than the median gap.	info	example
  .tsv	Download a ISO-8859-1 tab-separated text table (line 1: names; line 2: units; ISO 8601 times).	info	example
  .tsvp	Download a ISO-8859-1 .tsv file with line 1: name (units). Times are ISO 8601 strings.	info	example
  .tsv0	Download a ISO-8859-1 .tsv file without column names or units. Times are ISO 8601 strings.	info	example
  .wav	Download a .wav audio file. All columns must be numeric and of the same type.	info	example
  .xhtml	View a UTF-8 XHTML (XML) file with the data in a table. Times are ISO 8601 strings.	info	example

  
  For example, here is a request URL to download data formatted as an HTML table:
  https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]

  ArcGIS  .esriAsc
  .esriAsc is an old and inherently limited file format. If you have ArcGIS 10 or higher, we strongly recommend that you download gridded data from ERDDAP in a NetCDF .nc file, which can be opened directly by ArcGIS 10+ using the Make NetCDF Raster Layer tool in the Multidimension Tools toolbox.

  If you have ArcGIS 9.x or lower:
  ArcGIS is a family of Geographical Information Systems (GIS) products from ESRI: ArcView, ArcEditor, and ArcInfo. To download data for use with ArcGIS 9.x or lower: in ERDDAP, choose the .esriAscii file type to save a latitude longitude subset of data for just one point in time. The file's extension will be .asc. This file format was designed by ESRI to transfer coverage data between computers. Then, import the data file into your ArcGIS program:

  • For ArcInfo v8 or higher:
    1. Open ArcInfo.
    2. Use ArcToolbox.
    3. Use the Import to Raster : ASCII to Grid command
        
  • For ArcView's or ArcEditor's ArcMap:
    1. Open ArcMap.
    2. Choose a new empty map or load an existing map.
    3. Click on the ArcToolbox icon.
       1. Open Conversion Tools : To Raster : ASCII to Raster
          1. Input Raster File - Browse to select the .esriAscii .asc file.
          2. Output Raster File - Keep the default (or change it).
          3. Output Data Type - change to FLOAT.
          4. Click on OK.
       2. Open Data Management Tools : Projections and Transformations : Define Projection
          1. Input Dataset or Feature Class - Browse to select the Raster (GRID) that was just created (on disk).
          2. Coordinate System - click the icon to the right of the text box. That will open the Spatial Reference Properties window.
             1. Click the Select button.
             2. Choose the Geographic Coordinate Systems folder. (Most data in ERDDAP uses a 'geographic' projection, otherwise known as unprojected data or lat/lon data).
             3. Select on the Spheroid-based folder.
             4. Select the Clarke 1866.prj file and click Add.
             5. Click OK in the Spatial Reference Properties Window.
             6. Click OK in the Define Projection Window.
                 
  • For older ArcView (v3) - You need the Spatial Analyst extension, which is sold separately.
    1. Open ArcView
    2. Open Spatial Analyst
    3. Use Import Data Source : ASCII Raster

  Shapefiles - Sorry, ERDDAP currently does not distribute grid data as shapefiles.

  Ferret is a free program for visualizing and analyzing large and complex gridded datasets. Ferret should work well with all datasets in griddap since griddap is fully compatible with OPeNDAP. See the Ferret documentation. Note that the griddap dataset's OPeNDAP base URL that you use with Ferret's set data, for example,
  https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41
  won't ever have a file extension at the end.

  IDL - IDL is a commercial scientific data visualization program. To get data from ERDDAP into IDL, first use ERDDAP to select a subset of data and download a .nc file. Then, use these instructions to import the data from the .nc file into IDL.

  JSON .json files are widely used to transfer data to JavaScript scripts running on web pages. All .json responses from ERDDAP (metadata, gridded data, and tabular/in-situ data) use the same basic format: a database-like table. For data from grid datasets, ERDDAP flattens the data into a table with a column for each dimension and a column for each data variable. For example,

  {
    "table": {
      "columnNames": ["time", "latitude", "longitude", "analysed_sst"],
      "columnTypes": ["String", "float", "float", "double"],
      "columnUnits": ["UTC", "degrees_north", "degrees_east", "degree_C"],
      "rows": [
        ["2014-02-03T09:00:00Z", 34.9969, -134.995, 16.037],
        ["2014-02-03T09:00:00Z", 34.9969, -134.984, 16.033],
        ["2014-02-03T09:00:00Z", 34.9969, -134.973, null],
        ...
        ["2014-02-03T09:00:00Z", 36.9965, -132.995, 15.285]
      ]
    }
  }
  

  All .json responses from ERDDAP have
  • a table object (with name=value pairs).
  • a columnNames, columnTypes, and columnUnits array, with a value for each column.
  • a rows array of arrays with the rows and columns of data.
  • null's for missing values.
  Once you figure out how to process one ERDDAP .json table using your preferred JSON library or toolkit, it should be easy to process all other tables from ERDDAP in a similar way.

  JSONP (from .json) - Jsonp is an easy way for a JavaScript script on a web page to import and access data from ERDDAP. Requests for .geoJson, .json, and .ncoJson files may include an optional jsonp request by adding &.jsonp=functionName to the end of the query. Basically, this just tells ERDDAP to add functionName( to the beginning of the response and ")" to the end of the response. The first character of functionName must be an ISO 8859 letter or "_". Each optional subsequent character must be an ISO 8859 letter, "_", a digit, or ".". If originally there was no query, leave off the "&" in your query. After the data download to the web page has finished, the data is accessible to the JavaScript script via that JavaScript function. Here is an example using jsonp and Javascript with ERDDAP (thanks to Jenn Patterson Sevadjian of PolarWatch).

  MATLAB .mat users can use griddap's .mat file type to download data from within MATLAB. Here is a one line example:

  load(urlwrite('https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.mat?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]', 'test.mat'));

  (You may need to percent encode the query part of the URL.) The data will be in a MATLAB structure. The structure's name will be the datasetID (for example, jplMURSST41). The structure's internal variables will have the same names as in ERDDAP, (for example, use fieldnames(jplMURSST41)). If you download a 2D matrix of data (as in the example above), you can plot it with (for example):

  imagesc(jplMURSST41.longitude, jplMURSST41.latitude, squeeze(jplMURSST41.analysed_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.

  There are also Matlab Xtractomatic scripts for ERDDAP, which are particularly useful for getting environmental data related to points along an animal's track (e.g., GTOPP data).

  ERDDAP stores datetime values in .mat files as "seconds since 1970-01-01T00:00:00Z". To display one of these values as a String in Matlab, you can use, e.g.,
  datastr(cwwcNDBCMet.time(1)/86400 + 719529)
  86400 converts ERDDAP's "seconds since" to Matlab's "days since". 719529 converts ERDDAP's base time of "1970-01-01T00:00:00Z" to Matlab's "0000-01-00T00:00:00Z".

  .mat files have a maximum length for identifier names of 32 characters. If a variable name is longer than that, ERDDAP changes the name of the variable when writing the .mat file: it generates a hash digest of the variable name and appends that after the first 25 characters. Thus, long variable names that only differ at the end will still have unique names in the .mat file. ERDDAP administrators: you can avoid this problem by specifying shorter variable destinationNames.

  NetCDF .nc - Requests for .nc files return the requested subset of the dataset in a standard, NetCDF-3, 32-bit, .nc file.

  • Since NetCDF-3 files don't support variable length strings and only support chars with 1 byte per char, all String variables in ERDDAP (variable length, 2 bytes per char) will be stored as char array variables (1 byte per char) in the .nc file, using the ISO-8859-1 character set. The char variables will have an extra dimension indicating the maximum number of characters per string. Characters not in the ISO-8859-1 character set will be converted to '?'.
  • Since chars in NetCDF-3 files are only 1 byte per char, all char variables in ERDDAP (2 bytes per char) will be stored as chars (one byte per char) in the .nc file, using the ISO-8859-1 charset. Characters not in the ISO-8859-1 character set will be converted to '?'.
  • Since NetCDF-3 files do not support 64-bit long integers, all long variables in ERDDAP will be stored as double variables in the .nc file. Numbers from -2^53 to 2^53 will be stored exactly. Other numbers will be stored as approximations.

  If you are using NetCDF-Java, don't try to directly access an ERDDAP dataset or subset as a .nc file. (It won't work, mostly because that .nc file isn't a static, persistent file. It is a virtual file.) Instead, use one of these two options:

  • Most situations: Open the ERDDAP dataset as an OPeNDAP dataset. For example:

    NetcdfFile nc = NetcdfDataset.openFile("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41", null);  //pre v5.4.1 

    or

    NetcdfFile nc = NetcdfDatasets.openFile("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41", null); //v5.4.1+ 

    (don't use NetcdfFiles.open; it is for local files only) or

    NetcdfDataset nc = NetcdfDataset.openDataset("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41");  //pre v5.4.1

    or

    NetcdfDataset nc = NetcdfDatasets.openDataset("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41");  //v5.4.1+

    (NetcdfFiles are a lower level approach than NetcdfDatasets. It is your choice.)
    Don't use a file extension (e.g., .nc) at the end of the dataset's name.
    And don't specify a variable or a subset of the dataset at this stage.
  • Few situations: By hand in a browser or with a program like curl, download a .nc file with a subset of the dataset. Then, use NetCDF-Java to open and access the data in that local file, e.g., one of these options:

    NetcdfFile nc = NetcdfFile.open("c:\downloads\theDownloadedFile.nc");  //pre v5.4.1
    NetcdfFile nc = NetcdfFiles.open("c:\downloads\theDownloadedFile.nc");  //v5.4.1+
    NetcdfDataset nc = NetcdfDataset.openDataset("c:\downloads\theDownloadedFile.nc");  //pre v5.4.1
    NetcdfDataset nc = NetcdfDatasets.openDataset("c:\downloads\theDownloadedFile.nc");  //v5.4.1+

    (NetcdfFiles are a lower level approach than NetcdfDatasets. It is your choice.)
    This approach makes more sense if you want a local copy of the data subset, so that you can access it repeatedly (today, tomorrow, next week, ...) and quickly.

  In both cases, you can then do what you want with the nc object, for example, request metadata or request a subset of a variable's data.

  .ncHeader - Requests for .ncHeader files will return the header information (UTF-8 text) that would be generated if you used ncdump -h fileName on the corresponding .nc file.

  Ocean Data View .odvTxt - ODV users can download data in a ODV Generic Spreadsheet Format .txt file by requesting griddap's .odvTxt fileType. The dataset MUST include longitude, latitude, and time dimensions. Any longitude values (0 to 360, or -180 to 180) are fine. After saving the resulting file (with the extension .txt) in your computer:

  1. Open ODV.
  2. Use File : Open.
     • Change Files of type to Data Files (*.txt *.csv *.jos *.o4x).
     • Browse to select the .txt file you created in ERDDAP and click on Open. The data locations should now be visible on a map in ODV.
  3. If you downloaded a longitude, latitude slice of a dataset, use:
     • Press F12 or View : Layout Templates : 1 SURFACE Window to view the default isosurface variable.
     • If you want to view a different isosurface variable,
       • To define a new isosurface variable, use View : Isosurface Variables.
       • Right click on the map and choose Properties : Data : Z-axis to pick the new isosurface variable.
  4. See ODV's Help menu for more help using ODV.

  OPeNDAP Libraries - Since ERDDAP is an OPeNDAP-compatible data server, you can use any OPeNDAP client library, such as NetCDF-Java, NetCDF-C, NetCDF-Fortran, NetCDF-Perl, Java-DAP2, Ferret, or the Pydap Client, to get data from an ERDDAP griddap dataset. When creating the initial connection to an ERDDAP griddap dataset from any OPeNDAP library:

  • Don't include a file extension (e.g., .nc) at the end of the dataset's name.
  • Don't specify a variable or a subset of the dataset.
  
  Once you have made the connection to the dataset, you can request metadata or a subset of a variable's data.

  For example, with the NetCDF-Java library, you can use:

  NetcdfFile nc = NetcdfDataset.openFile("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41", null);  //pre v5.4.1

  or

  NetcdfFile nc = NetcdfDatasets.openFile("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41", null); //v5.4.1+

  (don't use NetcdfFile.open; it is for local files only) or

  NetcdfDataset nc = NetcdfDataset.openDataset("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41");  //pre v5.4.1

  or

  NetcdfDataset nc = NetcdfDatasets.openDataset("https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41");  //v5.4.1+

  (NetcdfFiles are a lower level approach than NetcdfDatasets. It is your choice.)
  Once you have the nc object, you can request metadata or a subset of a variable's data.

  Pydap Client users can access griddap datasets via ERDDAP's standard OPeNDAP services. See the Pydap Client instructions for accessing gridded data. Note that the name of a dataset in ERDDAP will always be a single word, (e.g., jplMURSST41 in the OPeNDAP dataset URL
  https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41 ) and won't ever have a file extension (unlike, for example, .nc for the sample dataset in the Pydap instructions).

  Python is a widely-used computer language that is very popular among scientists. In addition to the Pydap Client, you can use Python to download various files from ERDDAP as you would download other files from the web:

  import urllib
  urllib.urlretrieve("https://baseHttpsUrl/erddap/griddap/datasetID.fileType?query", "outputFileName")

  (You may need to percent encode the query part of the URL.)
  Or download the content to an object instead of a file:

  import urllib2
  response = urllib2.open("https://baseHttpsUrl/erddap/griddap/datasetID.fileType?query")
  theContent = response.read()

  There are other ways to do this in Python. Search the web for more information.

  erddapy (ERDDAP + Python, by Filipe Pires Alvarenga Fernandes) and
  erddap-python (by Favio Medrano)
  are Python libraries that "take advantage of ERDDAP’s RESTful web services and create the ERDDAP URL for any request like searching for datasets, acquiring metadata, downloading data, etc." They have somewhat different programming styles and slightly different feature sets, so it might be good to experiment with both to see which you prefer.

  "Jupyter Notebook is an open-source web application that allows you to create and share documents that contain live code, equations, visualizations and explanatory text" using any of over 40 programming languages, including Python and R. Here are two sample Jupyter Notebooks that access ERDDAP using Python: ERDDAP Advanced Search Test and ERDDAP Timing. Thanks to Rich Signell.

  R Statistical Package - R is an open source statistical package for many operating systems. In R, you can download a NetCDF version 3 .nc file from ERDDAP. For example:

  download.file(url="https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.nc?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]", destfile="/home/bsimons/test.nc")

  (You may need to percent encode the query part of the URL.) Then import data from that .nc file into R with the RNetCDF, ncdf, or ncdf4 packages available from CRAN. Or, if you want the data in tabular form, download and import the data in a .csv file. For example,

  download.file(url="https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.csv?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]", destfile="/home/bsimons/test.csv")
  test<-read.csv(file="/home/bsimons/test.csv")

  There are third-party R packages designed to make it easier to work with ERDDAP from within R: rerddap, rerddapXtracto, and plotdap. Thanks to rOpenSci and Roy Mendelssohn.

  There are also R Xtractomatic scripts for ERDDAP, which are particularly useful for getting environmental data related to points along an animal's track (e.g., GTOPP data).
   

  .timeGaps is a response which is unique to ERDDAP. It lets you view a list of gaps in a dataset's time values which are larger than the median gap. This is useful for ERDDAP administrators and end users when they want to know if there are unexpected gaps in the time values for a dataset that is expected to have regularly spaced time values. This option ignores all request constraints.
   

  .wav - ERDDAP can return data in .wav files, which are uncompressed audio files.

  • You can save any numeric data in .wav files, but this file format is clearly intended to be used with PCM digitized sound waves. We do not recommend saving other types of data in .wav files.
  • All of the data variables you select to save in a .wav file must have the same data type, e.g., int. Currently, because of a bug in Java 8, ERDDAP can't save float or double data. That should change when ERDDAP is run with Java 9.
  • For gridded datasets, ERDDAP doesn't write the axis variable data to the .wav files.
  • The data variable values are just written as a long sequence of numbers (the sound wave). Unfortunately, ERDDAP must create the entire .wav file before it can begin to send the file to you, so there will be a delay from when you submit the request and when you start to get the file. There is no limit in ERDDAP to the number of numbers that may be written to a .wav file, but requests for very large files may lead to timeout error messages because of the long time needed to create the file.
  • Data is written to .wav files using either the PCM_SIGNED encoding (for integer data types) or the PCM_FLOAT encoding (for floating point data types). Since long integer values aren't supported by PCM_SIGNED, ERDDAP writes longs as ints, by writing the high 4 bytes of the long to the file. Other than long values, data values are unchanged when they are written to .wav files.
  • If the dataset's global attributes include audioFrameRate and/or audioSampleRate attributes, those values (they should be the same) will be used as the frameRate and sampleRate. Otherwise, ERDDAP assigns a rate of 10000 frames (or samples) per second.
  • The .wav files will have several attributes describing how the sound data is stored in the file. Currently, no other metadata (e.g., the global attributes) is stored in the .wav files.
     
     

  Making an Image File 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	View a grayscale GeoTIFF .tif file (for latitude longitude data; longitude must be all below or all above 180).	info	example
  .kml	View a Google Earth .kml file (for latitude, longitude data only).	info	example
  .smallPdf	View a small .pdf image file with a graph or map.	info	example
  .pdf	View a standard, medium-sized .pdf image file with a graph or map.	info	example
  .largePdf	View a large .pdf image file with a graph or map.	info	example
  .smallPng	View a small .png image file with a graph or map.	info	example
  .png	View a standard, medium-sized .png image file with a graph or map.	info	example
  .largePng	View a large .png image file with a graph or map.	info	example
  .transparentPng	View a .png image file (just the data, without axes, landmask, or legend).	info	example

  Image Size - ".small" and ".large" were ERDDAP's original system for making different-sized images. Now, for .png and .transparentPng images (not other image file types), you can also use the &.size=width|height parameter to request an image of any size.

  .transparentPng - The .transparentPng file type will make a graph or map without the graph axes, landmask, or legend, and with a transparent (not opaque white) background. This option can be used for any type of graph or map. When &.draw= is set to anything other than surface, the default image size is 360x360 pixels. Use the &.size=width|height parameter to specify a different size. When &.draw= is set to surface, ERDDAP makes an image where each data point becomes one pixel, which may result in a huge image. If the request takes too long or fails (perhaps for an odd apparent reason, like a Proxy Error) either use a stride (see below) value greater than 1 (e.g., 5) for the x and y axis variables, or use the &.size=width|height parameter to restrict the image size, so that the image isn't huge.

  Incompatibilities
  Some results file types have restrictions. For example, Google Earth .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.

  Command Line Downloads with curl
  If you want to download a series of files from ERDDAP, you don't have to request each file's ERDDAP URL in your browser, sitting and waiting for each file to download. If you are comfortable writing computer programs (e.g., with C, Java, Python, Matlab, r) or scripts (e.g., Python, bash, tcsh, PowerShell, or Windows batch files), you can write a program or script with a loop (or a series of commands) that imports all of the desired data files. Or, if you are comfortable running command line programs (from a Linux or Windows command line, or a Mac OS Terminal), you can use curl (or a similar program like wget) to save results files from ERDDAP into files on your hard drive, without using a browser or writing a computer program or script.

  ERDDAP + curl is amazingly powerful and allows you to use ERDDAP in many new ways.
  On Linux and Mac OS X, curl is probably already installed.
  On Mac OS X, to get to a command line, use "Finder : Go : Utilities : Terminal".
  On Windows, you need to download curl (the "Windows 64 - binary, the curl project" variant worked for me on Windows 10) and install it.
  On Windows, to get to a command line, click on "Start" and type "cmd" into the search text field.
  Please be kind to other ERDDAP users: run just one script or curl command at a time.
  Instructions for using curl are on the curl man page and in this curl tutorial.
  But here is a quick tutorial related to using curl with ERDDAP:

  • To download and save one file, use
    curl --compressed -g "erddapUrl" -o fileDir/fileName.ext
    where --compressed tells curl to request a compressed response and automatically decompress it,
      -g disables curl's globbing feature,
      erddapUrl is any ERDDAP URL that requests a data or image file, and
      -o fileDir/fileName.ext specifies the name for the file that will be created.
    For example,

    curl --compressed -g "https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.png?analysed_sst%5B(2002-06-01T09:00:00Z):(2002-07-01T09:00:00Z)%5D%5B(29)%5D%5B(-135)%5D&.draw=linesAndMarkers&.vars=time%7Canalysed_sst%7C&.marker=1%7C3&.color=0xFF9900&.colorBar=%7CC%7CLinear%7C%7C%7C" -o jplMURSST41_example.png

    (That example includes --compressed because it is a generally useful option, but there is little benefit to --compressed when requesting .png files because they are already compressed.)

    In curl, as in many other programs, the query part of the erddapUrl must be percent encoded. To do this, you need to convert special characters (other than the initial '&' and the main '=' of a constraint) into the form %HH, where HH is the 2 digit hexadecimal value of the character. Usually, you just need to convert a few of the punctuation characters: % into %25, & into %26, " into %22, < into %3C, = into %3D, > into %3E, + into %2B, | into %7C, space into %20, [ into %5B, ] into %5D, and convert all characters above #127 into their UTF-8 bytes and then percent encode each byte of the UTF-8 form into the %HH format (ask a programmer for help). Note that percent encoding is generally required when you access ERDDAP via software other than a browser. Browsers usually handle percent encoding for you. In some situations, you need to percent encode all characters other than A-Za-z0-9_-!.~'()* . Programming languages have tools to do this (for example, see Java's java.net.URLEncoder and JavaScript's encodeURIComponent()) and there are websites that percent encode/decode for you.
     

  • To download and save many files in one step, use curl with the globbing feature enabled:
    curl --compressed "erddapUrl" -o fileDir/fileName#1.ext
    Since the globbing feature treats the characters [, ], {, and } as special, you must percent encode them in the erddapURL as %5B, %5D, %7B, %7D, respectively. Then, in the erddapUrl, replace a zero-padded number (for example 01) with a range of values (for example, [01-15] ), or replace a substring (for example 5day) with a list of values (for example, {5day,8day,mday} ). The #1 within the output fileName causes the current value of the range or list to be put into the output fileName. For example,

    curl --compressed "https://coastwatch.pfeg.noaa.gov/erddap/griddap/erdBAssta5day.png?sst%5B%282010-09-[01-05]T12:00:00Z%29%5D%5B%5D%5B%5D%5B%5D&.draw=surface&.vars=longitude|latitude|sst&.colorBar=|||||" -o BAssta5day201009#1.png

  • To access a password-protected, private ERDDAP dataset with curl via https, use this two-step process:
     
    1. Log in (authenticate) and save the certificate cookie in a cookie-jar file:

       curl -v --data 'user=myUserName&password=myPassword' -c cookies.txt -b cookies.txt -k https://baseurl:8443/erddap/login.html

    2. Repeatedly make data requests using the saved cookie:

       curl --compressed -v -c cookies.txt -b cookies.txt -k https://baseurl:8443/erddap/griddap/datasetID.fileType?query -o outputFileName

    Some ERDDAP installations won't need the port number (:8443) in the URL.
    (Thanks to Liquid Robotics for the starting point and Emilio Mayorga of NANOOS and
    Paul Janecek of Spyglass Technologies for testing.)
     
• 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 projection constraint query which can request:
  • One or more dimension (axis) variables, for example
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?latitude[0:100:1000] .
  • One or more data variables, for example
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[0][0:1000:16383][0:1000:32767] .
    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 return information about the dataset (for example, .das, .dds, and .html), but don't return all of the actual data values. For example,
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.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) to minimize the download time.

  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. ...)
  • 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).
  • stop is the index of the last desired value.
  • 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,
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.dds?analysed_sst
    For data variables, 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 to minimize the download time.
  • last - ERDDAP extends the OPeNDAP standard by interpreting a start or stop value of last as the last available index value. You can also use the notation last-n (e.g., last-10) to specify the last index minus some number of indices. You can use '+' in place of '-'. The number of indices can be negative.
  • griddap extends the standard OPeNDAP 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][latitude][longitude] dimension values
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[(1022922000)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]
    is (at least at the time of writing this) equivalent to this example with dimension indices
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[0][0:1000:16383][0:1000:32767]
    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.
  • [high:low] or [(high):(low)] -- Starting with ERDDAP v2.17, if a user specifies the high and low values in the wrong order, e.g., [high:low] or [(high):(low)], ERDDAP will swap the specified high and low values to make the request valid. This is particularly useful for the few datasets where the latitude values in the dataset are stored high to low: previously, these datasets had to be known and handled separately by users; now, if users specify the values in the "incorrect" order, ERDDAP will repair the request.
  • griddap always stores date/time values as double precision floating point numbers (seconds since 1970-01-01T00:00:00Z, sometimes with some number of milliseconds). Here is an example of a query which includes date/time numbers:
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[(1022922000)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]
    The more human-oriented fileTypes (notably, .csv, .tsv, .htmlTable, .odvTxt, and .xhtml) display date/time values as ISO 8601:2004 "extended" date/time strings (e.g., 2002-08-03T12:30:00Z, but some variables include milliseconds, e.g., 2002-08-03T12:30:00.123Z).
    ERDDAP has a utility to Convert a Numeric Time to/from a String Time. See also: How ERDDAP Deals with Time.
  • For the time dimension, griddap extends the OPeNDAP standard by allowing you to specify an ISO 8601:2004 "extended" date/time string in parentheses, which griddap then converts to the internal number (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:ss.SSSZ, where Z is 'Z' or a ±hh or ±hh:mm offset from the Zulu/GMT time zone. If you omit Z and the offset, the Zulu/GMT time zone is used. Separately, if you omit .SSS, :ss.SSS, :mm:ss.SSS, or Thh:mm:ss.SSS from the ISO date/time that you specify, the missing fields are assumed to be 0. In some places, ERDDAP accepts a comma (ss,sss) as the seconds decimal point, but ERDDAP always uses a period when formatting times as ISO 8601 strings. The example below is equivalent (at least at the time of writing this) to the examples above:
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]
    ERDDAP is "lenient" when it parses date/time strings. That means that date/times with the correct format, but with month, date, hour, minute, and/or second values that are too large or too small will be rolled to the appropriate date/times. For example, ERDDAP interprets 2001-12-32 as 2002-01-01, and interprets 2002-01-00 as 2001-12-31. (It's not a bug, it's a feature! We understand that you may object to this if you are not familiar with lenient parsing. We understand there are circumstances where some people would prefer strict parsing, but there are also circumstances where some people would prefer lenient parsing. ERDDAP can't have it both ways. This was a conscious choice. Lenient parsing is the default behavior in Java, the language that ERDDAP is written in and arguably the most-used computer language. Also, this behavior is consistent with ERDDAP's conversion of requested grid axis values to the nearest valid grid axis value. And this is consistent with some other places in ERDDAP that try to repair invalid input when the intention is clear, instead of just returning an error message.) ERDDAP has a utility to Convert a Numeric Time to/from a String Time. See also: How ERDDAP Deals with Time.
  • (last) - ERDDAP interprets a start or stop value of (last) as the last available index. You can also use the notation (last-d) (e.g., last-10.5) to specify the last index's value minus some number, which is then converted to the nearest index. You can use '+' in place of '-'. The number can be negative. For a time axis, the number is interpreted as some number of seconds.
  • Can users extract data from a polygon-defined geographic area?
    No. ERDDAP does not support that. You need to calculate the lat lon bounding box for the polygon (it is easy to calculate: the lon range will be minLon to maxLon, the lat range will be minLat to maxLat) and request that multidimensional rectangle from ERDDAP. You can then do the polygon extraction (or calculations) in your favorite analysis software (ArcGIS, Matlab, Python, R, ...). An advantage of this approach is that there is no limit to the number of points that define the polygon. Note that this is the way the OPeNDAP standard (which ERDDAP uses for these requests) works: users request a multidimensional rectangular subset of the original arrays and get a response in similar arrays (the same axis and data variable names, just smaller arrays,
    e.g., var[minTime:maxTime][minLat:maxLat][minLon:maxLon]), so it is unclear what data structure the user would want for a polygon response.
     
  • Graphics Commands - griddap extends the OPeNDAP 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 (PNG or PDF) 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. The commands are:
    • &.bgColor=bgColor
      This specifies the background color of a graph (not a map). The color is specified as an 8 digit hexadecimal value in the form 0xAARRGGBB, where AA, RR, GG, and BB are the opacity, red, green and blue components, respectively. The canvas is always opaque white, so a (semi-)transparent graph background color blends into the white canvas. The color value string is not case sensitive. For example, a fully opaque (ff) greenish-blue color with red=22, green=88, blue=ee would be 0xff2288ee. Opaque white is 0xffffffff. Opaque light blue is 0xffccccff. The default on this ERDDAP is 0xffccccff.
    • &.colorBar=palette|continuous|scale|min|max|nSections
      This specifies the settings for a color bar. The sub-values are:
      • palette - All ERDDAP installations support a standard set of palettes: BlackBlueWhite, BlackRedWhite, BlackWhite, BlueWhiteRed, LightRainbow, Ocean, OceanDepth, Rainbow, RedWhiteBlue, ReverseRainbow, Topography, TopographyDepth, WhiteBlack, WhiteBlueBlack, WhiteRedBlack. Some ERDDAP installations support additional options. See a Make A Graph web page for a complete list. 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 variables.
      • scale - must be either no value (the default), Linear, or Log. The default is different for different variables.
      • min - The minimum value for the color bar. The default is different for different variables.
      • max - The maximum value for the color bar. The default is different for different variables.
      • nSections - The preferred number of sections (for Log color bars, this is a minimum value). The default is different for different colorBar settings.
      If you don't specify one of the sub-values, the default for the sub-value will be used.
    • &.color=value
      This specifies the color for data lines, markers, vectors, etc. The value must be specified as an 0xRRGGBB value (e.g., 0xFF0000 is red, 0x00FF00 is green). The color value string is not case sensitive. The default is 0x000000 (black).
    • &.draw=value
      This specifies how the data will be drawn, as lines, linesAndMarkers, markers, sticks, surface, or vectors.
    • &.font=scaleFactor
      This specifies a scale factor for the font (e.g., 1.5 would make the font 1.5 times as big as normal).
    • &.land=value
      This specifies how the landmask should be drawn:
      under (best for most variables) draws the landmask under the data.
      over draws the landmask over the data.
      outline just draws the landmask outline, political boundaries, lakes, and rivers.
      off doesn't draw anything.
      The default is different for different variables (under the ERDDAP administrator's control via a drawLandMask setting in datasets.xml, or via the fallback drawLandMask setting in setup.xml). under is the best choice for most variables.
    • &.legend=value
      This specifies whether the legend on PNG images (not PDF's) should be at the Bottom (default), Off, or Only (which returns only the legend).
    • &.marker=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)
    • &.size=width|height
      For PNG images (not PDF's), this specifies the desired size of the image, in pixels. This allows you to specify sizes other than the predefined sizes of .smallPng, .png, and .largePng, or the variable size of .transparentPng.
    • &.trim=trimPixels
      For PNG images (not PDF's), this tells ERDDAP to make the image shorter by removing all whitespace at the bottom, except for trimPixels.
    • &.vars='|'-separated list
      This is a '|'-separated list of variable 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=value
      This 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=min|max|ascending|scale
      &.yRange=min|max|ascending|scale
      The .xRange and .yRange commands can have any number of values.
      If there are fewer than 4 values, the missing values are treated as default values.
      If there are more than 4 values, the extra values are ignored.
      • min and max specify the range of the X and Y axes. They can be numeric values or nothing (the default, which tells ERDDAP to use an appropriate value based on the data).
      • ascending specifies whether the axis is drawn the normal way (ascending), or reversed (descending, flipped). ascending can be nothing or true, t, false, or f. These values are case insensitive. The default is true. ascending applies to graphs only, not maps.
      • scale specifies a preference for the axis scale. scale can be nothing (the default, which is dependent on the x or y axis variable's colorBarScale setting), or Linear, or Log. These values are case insensitive. scale applies to graphs only, not maps. scale will be ignored (and the axis will be linear) if the axis is a time axis, or if the minimum value on the axis is <=0, or if the axis range is very narrow.
    
    A sample URL to view a .png of a graph is
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.png?analysed_sst[(2002-06-01T09:00:00Z):(2002-07-01T09:00:00Z)][(29)][(-135)]&.draw=linesAndMarkers&.vars=time|analysed_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:
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.graph?analysed_sst[(2002-06-01T09:00:00Z):(2002-07-01T09:00:00Z)][(29)][(-135)]&.draw=linesAndMarkers&.vars=time|analysed_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 view or download the data that was graphed:
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[(2002-06-01T09:00:00Z):(2002-07-01T09:00:00Z)][(29)][(-135)]&.draw=linesAndMarkers&.vars=time|analysed_sst|&.marker=1|3&.color=0xFF9900&.colorBar=|C|Linear|||

    A sample URL to view a .png of a map is
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.png?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]&.draw=surface&.vars=longitude|latitude|analysed_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:
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.graph?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]&.draw=surface&.vars=longitude|latitude|analysed_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 view or download the data that was mapped:
    https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.htmlTable?analysed_sst[(2002-06-01T09:00:00Z)][(-89.99):1000:(89.99)][(-179.99):1000:(180.0)]&.draw=surface&.vars=longitude|latitude|analysed_sst&.colorBar=Rainbow|C|Linear|0|32|

Other Information

• Log in to access private datasets.
  Many ERDDAP installations don't have authentication enabled and thus don't provide any way for users to login, nor do they have any private datasets.

  Some ERDDAP installations do have authentication enabled. Currently, ERDDAP only supports authentication via Google-managed email accounts, which includes email accounts at NOAA and many universities. If an ERDDAP has authentication enabled, anyone with a Google-managed email account can log in, but they will only have access to the private datasets that the ERDDAP administrator has explicitly authorized them to access. For instructions on logging into ERDDAP from a browser or via a script, see Access to Private Datasets in ERDDAP.

• Requests for a long time range (>30 time points) from a gridded dataset are prone to time out failures, which often appear as Proxy Errors, because it takes significant time for ERDDAP to open all of the data files one-by-one. If ERDDAP is otherwise busy during the request, the problem is more likely to occur. If the dataset's files are compressed, the problem is more likely to occur, although it's hard for a user to determine if a dataset's files are compressed. The solution is to make several requests, each with a smaller time range. How small of a time range? Start really small (~30 time points?), then (approximately) double the time range until the request fails, then go back one doubling. Then make all the requests (each for a different chunk of time) needed to get all of the data. An ERDDAP administrator can lessen this problem by increasing the Apache timeout settings.
   
• Data Model
  Each griddap dataset can be represented as:
  • An ordered list of one or more 1-dimensional axis variables, each of which has an associated dimension with the same name.
    • Each axis variable has data of one specific data type. See the Data Type documentation for details. If the data source has a dimension with a size but no values, ERDDAP uses the integer values 0, 1, 2, ... Axis variables can't contain char or String data.
    • The minimum number of axis variables is 1.
    • The maximum number of axis variables is 2147483647, but most datasets have 4 or fewer.
    • The maximum size of a dimension is 2147483647 values.
    • The maximum product of all dimension sizes is, in theory, about ~9e18.
    • Missing values are not allowed.
    • The values MUST be sorted in either ascending (recommended) or descending order. Unsorted values are not allowed because [(start):(stop)] requests must translate unambiguously into a contiguous range of indices. Tied values are not allowed because requests for a single [(value)] must translate unambiguously to one index. Also, the CF Conventions require that "coordinate variables", as it calls them, be "ordered monotonically".
    • 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 metadata which is a set of 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 data type.
    • 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, _).
    • The maximum number of data variables in a dataset is 2147483647, but datasets with greater than about 100 data variables will be awkward for users.
    • Each data variable has metadata which is a set of Key=Value pairs.
  • The dataset has Global metadata which is a set of Key=Value pairs.
  • Note about metadata: each variable's metadata and the global metadata is a set of 0 or more Key=Value pairs.
    • Each Key is a String consisting of a letter (A-Z, a-z) and then 0 or more other characters (A-Z, a-z, 0-9, '_').
    • Each Value is an array of one (usually) or more values of one data type.
       
• Special Variables
  ERDDAP is aware of the spatial and temporal features of each dataset. The longitude, latitude, altitude, depth, and time axis variables (when present) always have specific names and units. This makes it easier for you to identify datasets with relevant data, to request spatial and temporal subsets of the data, to make images with maps or time-series, and to save data in geo-referenced file types (e.g., .esriAscii and .kml).
  • 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 depth axis variable (if present) always has the name "depth" and the units "m" below sea level. Locations below sea level have positive depth values.
  • In griddap, a time axis variable (if present) always has the name "time" and the units "seconds since 1970-01-01T00:00:00Z". If you request data and specify a start and/or stop value for the time axis, you can specify the time as a number (in seconds since 1970-01-01T00:00:00Z) or as a String value (e.g., "2002-12-25T07:00:00Z" in the GMT/Zulu time zone).
     
• Incompatibilities
  • File Types - Some results file types have restrictions. For example, .kml is only appropriate for results with a range of 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 accordingly. Requesting compression is optional, but compressed responses are often 3-10 times faster, so this is a big time savings if you are downloading lots of large files. (Note that there is no benefit to requesting compressed .png files since the files' contents are already compressed.)
  • By default, browsers and OPeNDAP clients always request compressed data and decompress the returned data.
  • With curl, add --compressed to the command line to tell curl to request a compressed response and automatically decompress it.
  • With other client software, you have explicitly set this up.
    Here is a Java example.
    Here is a Python example (although you should either handle deflate'd responses or not request deflate).
  
   
• How to Cite a Dataset in a Paper
  It is important to let readers of your paper know how you got the data that you used in your paper. For each dataset that you used, please look at the dataset's metadata in the Dataset Attribute Structure section at the bottom of the .html page for the dataset, e.g.,
  https://coastwatch.pfeg.noaa.gov/erddap/griddap/jplMURSST41.html .
  The metadata sometimes includes a required or suggested citation format for the dataset. The "license" metadata sometimes lists restrictions on the use of the data.

  To generate a citation for a dataset:
  If you think of the dataset as a scientific article, you can generate a citation based on the author (see the "creator_name" or "institution" metadata), the date that you downloaded the data, the title (see the "title" metadata), and the publisher (see the "publisher_name" metadata). If possible, please include the specific URL(s) used to download the data. If the dataset's metadata includes a Digital Object Identifier (DOI), please include that in the citation you create.
   

• Errors
  Like other parts of the Internet (e.g., Tomcat, Apache, routers, your browser), ERDDAP uses various HTTP status/error codes to make it easy to distinguish different types of errors, including:
  • 400 Bad Request - for syntax errors in the request URL and other request errors that will never succeed. If you fix the stated problem, your request should succeed (or you'll get a different error message for a different problem).
  • 401 Unauthorized - when the user isn't currently authorized to access a given dataset. If you get this and think it unwarranted, please email this ERDDAP's administrator to try to resolve the problem.
  • 403 Forbidden - when the user's IP address is on this ERDDAP's blacklist. If you get this and think it unwarranted, please email this ERDDAP's administrator to try to resolve the problem.
  • 404 Not Found - for datasetID not found (perhaps temporarily), "Your query produced no matching results.", or other request errors If the datasetID was not found but was there a few minutes ago, wait 15 minutes and try again.
  • 408 Timeout - for timeouts. Often, these can be fixed by making a request for less data, e.g., a shorter time period.
  • 413 Payload Too Large - when there isn't enough memory currently (or ever) available to process the response, or when the response is too large for the requested file type. Often, these can be fixed by making a request for less data, e.g., a shorter time period.
  • 416 Range Not Satisfiable - for invalid byte range requests. Note that ERDDAP's "files" system does not allow byte range requests to the individual .nc, .hdf, .bz2, .gz, .gzip, .tar, .tgz, .z, and .zip files (although the exact list may vary for different ERDDAP installations) because that approach is horribly inefficient (tens/hundreds/thousands of requests and the transfer of tons of data unnecessarily) and some of the client software is buggy in a way that causes problems for ERDDAP (tens/hundreds/thousands of open/broken sockets). Instead, either download the entire file (especially if you need repeated use of different parts of the file) or use the griddap or tabledap services to request a subset of a dataset via an (OPeN)DAP request. That's what DAP was designed for and does so well. Just because you can saw a log with a steak knife (sometimes) doesn't make it a good idea -- use your chainsaw.
  • 500 Internal Server Error - for errors that aren't the user's fault or responsibility. For code=500 errors that look like they should use a different code, or for errors that look like bugs in ERDDAP, please email the URL and error message to erd.data at noaa.gov .

  If the error response was generated by ERDDAP (not by some other part of the Internet, e.g., Tomcat, Apache, routers, or your browser), it will come with an (OPeN)DAPv2.0-formatted, plain text, UTF-8-encoded error message as the payload of the response, e.g.,
  Error {
      code=404;
      message="Not Found: Your query produced no matching results. (time>=2019-03-27T00:00:00Z is outside of the variable's actual_range: 1970-02-26T20:00:00Z to 2019-03-26T15:00:00Z)";
  }
  Notes:

  • The message is a JSON-encoded string. The first few words, e.g., Not Found, are the generic name of the HTTP error code (e.g., HTTP error 404).
  • Of course, status code 200 OK (with the relevant payload) is used for completely successful requests.
  • Errors generated by other parts of the Internet (e.g., Tomcat, Apache, routers, or your browser) won't return an (OPeN)DAPv2.0-formatted, plain text, error message. In fact, they may not return any payload with the HTTP error code. In a browser, errors are obvious. But in a script, the best way to check for errors is to look at the HTTP status code first (is it 200=OK ?) and only secondarily see if there is an error message payload (which may not be (OPeN)DAPv2.0-formatted).
  • If you need help resolving a problem, email the URL and error message to this ERDDAP's administrator to try to resolve the problem. Or, you can join the ERDDAP Google Group / Mailing List and post the URL, the error message, and your question there.
  • If you see errors that have been assigned the wrong HTTP status code (especially code=500 errors that should be 4xx errors) or might be evidence of a bug in ERDDAP, please email the URL and error message to erd.data at noaa.gov .
  
   

Contact Us

If you have questions, suggestions, or comments about ERDDAP in general (not this specific ERDDAP installation or its datasets), please send an email to bob dot simons at noaa dot gov and include the ERDDAP URL directly related to your question or comment.

Or, you can join the ERDDAP Google Group / Mailing List by visiting https://groups.google.com/forum/#!forum/erddap and clicking on "Apply for membership". Once you are a member, you can post your question there or search to see if the question has already been asked and answered.