Climate Data Online Web Services: Data

This version of the Climate Data Online web services API is deprecated. Please switch to Climate Data Online web services API version 2.

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 Data

To retrieve the data available for a set of observation parameters, use one of the URIs below with your token. CDO data includes elements such as data type (dataType), station ID {station), data value (value), and related data attributes.

URI Patterns

/datasets/{dataSet}/data
/datasets/{dataSet}/datatypes/{dataType}/data
/datasets/{dataSet}/locationtypes/{locationType}/data
/datasets/{dataSet}/locationtypes/{locationType}/datatypes/{dataType}/data
/datasets/{dataSet}/locationtypes/{locationType}/locations/{location}/data
/datasets/{dataSet}/locationtypes/{locationType}/locations/{location}/datatypes/{dataType}/data
/datasets/{dataSet}/locationtypes/{locationType}/locations/{location}/stations/{station}/data
/datasets/{dataSet}/locationtypes/{locationType}/locations/{location}/stations/{station}/datatypes/{dataType}/data
/datasets/{dataSet}/locations/{location}/data
/datasets/{dataSet}/locations/{location}/datatypes/{dataType}/data
/datasets/{dataSet}/locations/{location}/stations/{station}/data
/datasets/{dataSet}/locations/{location}/stations/{station}/datatypes/{dataType}/data
/datasets/{dataSet}/stations/{station}/data
/datasets/{dataSet}/stations/{station}/datatypes/{dataType}/data

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, .json, or .csv 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.
year 2011 If nothing is specified, the system will default to the current year (integer) optional.
month 4 If nothing is specified, the system will default to the current month (integer) optional
startday 15 The day of the month given to limit the beginning of the search. This should be an integer numbered 1 through 31 (for each day of the month). This is optional.
endday 30 The day of the month given to limit the end of the search. This should be an integer numbered 1 through 31 (for each day of the month) and should be limited to be the same or greater than the startday value. This is optional.
page 1 Results with over 10 items will be paginated. This variable allows the choice of which page of data is to be selected. This variable only accepts an integer as input and is optional.

URI Examples

Click on the links below and a preview will display example results from
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/GHCND/locations/FIPS:AS/data?year=2001&month=1

http://www.ncdc.noaa.gov/cdo-services/services/datasets/NORMAL_DLY/stations/GHCND:USW00014895/datatypes/dly-tmax-normal/data?year=2010&month=4

http://www.ncdc.noaa.gov/cdo-services/services/datasets/PRECIP_HLY/locations/ZIP:28801/datatypes/HPCP/data?year=1980&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