Climate Data Online: Web Services Documentation

Getting Started with Web Services v2

NCDC's Climate Data Online (CDO) offers web services that provide access to current data. This API is for developers looking to create their own scripts or programs that use the CDO database of weather and climate data. An access token is required to use the API, and each token will be limited to five requests per second and 10,000 requests per day.



Step 1: Request token

In order to access the CDO web services a token must first be obtained from the token request page.



Step 2: Make a request

To make a request use the base url with one of the endpoint paths appended.

Base URL

https://www.ncei.noaa.gov/cdo-web/api/v2/{endpoint}

Endpoints

Endpoint Description
/datasets A dataset is the primary grouping for data at NCDC.
/datacategories A data category is a general type of data used to group similar data types.
/datatypes A data type is a specific type of data that is often unique to a dataset.
/locationcategories A location category is a grouping of similar locations.
/locations A location is a geopolitical entity.
/stations A station is a any weather observing platform where data is recorded.
/data A datum is an observed value along with any ancillary attributes at a specific place and time.


Header

header usage Description
token curl -H "token:<token>" "url"
$.ajax({ url:<url>, data:{<data>}, headers:{ token:<token> } })		 The token obtained from the token request page.


Pagination

Parameter Example Description
limit 50 Limits the amount of results returned to 50.
offset 85 Begin with record number 85.




Step 3: Get a response

All responses are JSON and will be a single item or a collection of items with metadata.

Single item

{
	"id": "GSOY",
	"name": "Global Summary of the Year",
	"datacoverage": 1,
	"mindate": "1763-01-01",
	"maxdate": "2015-01-01"
}

Collection of items with metadata

{
	"results": [
		{
			"id": "GSOY",
			"name": "Global Summary of the Year",
			"datacoverage": 1,
			"mindate": "1763-01-01",
			"maxdate": "2015-01-01"
		},
		...
	],
	"metadata": {
		"resultset": {
			"limit": 25,
			"count": 11,
			"offset": 1
		}
	}
}