Climate Data Online Web Services: Datasets
Base URL Address
Every request should begin with the following standard URL. All requests must begin with this base URL.
| Base URL |
|---|
| http://www.ncdc.noaa.gov/cdo-services/services |
Retrieve Datasets
To retrieve the datasets that are available, use the URIs below; and fill in your token for YOUR_TOKEN. Typical results contain the dataset ID (id), the name (name), description (description), minimum date of available data (minDate), maximum date of available data (maxDate), and data attributes which specify the flags available for quality control of each dataset.
URI Patterns
/datasets/{dataSetId}
Output
CDO Web Services returns data output specified by the MIME type of application's request to the CDO Web Service system. For example, sending a request to the CDO services with a request type of "application/json" will retrieve JSON formatted data from the service. Output can also be specified by appending .xml or .json to the end of the service URI address and before any query-type parameters.
Additional Parameters
Below is a list of query parameters that are available for this URI pattern. Construct the web service target from the base URL and the URI patterns above then add these parameters after the question mark query separator (with each field-value pair separated by an ampersand).
| Parameter | Example | Description |
|---|---|---|
| token | This must be a valid token token supplied to you by NCDC's Climate Data Online access token generator. This is a required option. No data responses will be returned without a valid token. | |
| startdate | 20000101 | The date format pattern to limit the start date of the web service query. This is a string date mask represented by "yyyyMMdd" where yyyy is a 4-digit year, MM is the 2-digit month, and dd is the 2-digit day. Optional. (Note: not used for Normals) |
| enddate | 20101231 | The date format pattern to limit the end date of the web service query. This is a string date mask represented by "yyyyMMdd" where yyyy is a 4-digit year, MM is the 2-digit month, and dd is the 2-digit day. Optional. (Note: not used for Normals) |
| page | 1 | Results with over 10 items will be paginated. This controls which page of data is returned from the service. This variable only accepts an integer as input and is optional. |
| year | 2010 | Used for Annual Normals to specify which yearly set of normals to use. Currently only available from 1981-2010, so specify 2010 as the value. This is a string date mask represented by "yyyy" where yyyy is a 4-digit year. |
| month | 05 | Used for Annual Normals to specify which month to display for Annual Normals. Values include 01-12. This is a string date mask represented by "MM" where MM is the 2-digit month, |
Examples
each REST query. Select either XML or JSON to view each respective format.
Copy the URL listed below to use as a reference.
*Note: Your token is required to use these queries
http://www.ncdc.noaa.gov/cdo-services/services/datasets
http://www.ncdc.noaa.gov/cdo-services/services/datasets/GHCND
http://www.ncdc.noaa.gov/cdo-services/services/datasets/NORMAL_DLY
http://www.ncdc.noaa.gov/cdo-services/services/datasets/GHCND/locationsearch?latitude=35.59528&longitude=-82.55667
http://www.ncdc.noaa.gov/cdo-services/services/datasets/PRECIP_HLY/locations/ZIP:28801/datatypes/HPCP/data?year=1987&month=7&day=17
Troubleshooting
If you are having issues retrieving data, please check the following:
- Check code for typos paying close attention to case
- Double check your token
- Try the full RESTful URL in a web browser to see if you are getting the same results