NOAA Climate Data Online (CDO) API Reference

Base URL

https://www.ncdc.noaa.gov/cdo-web/api/v2

Authentication

• API Token: REQUIRED. Request a free token at https://www.ncdc.noaa.gov/cdo-web/token
• Pass as HTTP header: Token: YOUR_TOKEN

Rate Limits

• 5 requests per second per token.
• 10,000 requests per day per token.
• Queries are limited to 1,000 results per request (use offset for pagination).
• Date ranges limited to 1 year per request for the /data endpoint.

Common Parameters (apply to most endpoints)

Key Endpoints

1. Data (Observations)

GET /data

Returns actual observation data. This is the primary data retrieval endpoint.

Required parameters: datasetid, startdate, enddate.

Example -- daily max temperature for a station:

curl -H "Token: YOUR_TOKEN" \
  "https://www.ncdc.noaa.gov/cdo-web/api/v2/data?datasetid=GHCND&datatypeid=TMAX&stationid=GHCND:USW00013874&startdate=2024-01-01&enddate=2024-01-31&units=metric&limit=31"

Response:

{
  "metadata": {
    "resultset": {
      "offset": 1,
      "count": 31,
      "limit": 31
    }
  },
  "results": [
    {
      "date": "2024-01-01T00:00:00",
      "datatype": "TMAX",
      "station": "GHCND:USW00013874",
      "attributes": ",,W,2400",
      "value": 12.2
    },
    {
      "date": "2024-01-02T00:00:00",
      "datatype": "TMAX",
      "station": "GHCND:USW00013874",
      "attributes": ",,W,2400",
      "value": 8.9
    }
  ]
}

units=standard requests scaled US customary units (temperature in Fahrenheit); units=metric requests scaled metric units (Celsius). When units is omitted, native dataset scaling applies (GHCND raw temperature uses tenths of Celsius). Save the requested units with the observations.

2. Datasets

GET /datasets
GET /datasets/{id}

Lists available datasets or gets details for one.

Example:

curl -H "Token: YOUR_TOKEN" \
  "https://www.ncdc.noaa.gov/cdo-web/api/v2/datasets?limit=10"

Key Dataset IDs:

3. Data Types

GET /datatypes
GET /datatypes/{id}

Lists available data types, optionally filtered by dataset.

Example:

curl -H "Token: YOUR_TOKEN" \
  "https://www.ncdc.noaa.gov/cdo-web/api/v2/datatypes?datasetid=GHCND&limit=50"

Common GHCND Data Types:

4. Stations

GET /stations
GET /stations/{id}

Find weather stations, optionally filtered by location, dataset, or extent.

Additional Parameters:

Example -- stations near Asheville, NC with daily data:

curl -H "Token: YOUR_TOKEN" \
  "https://www.ncdc.noaa.gov/cdo-web/api/v2/stations?datasetid=GHCND&locationid=ZIP:28801&limit=10"

Response:

{
  "metadata": {"resultset": {"offset": 1, "count": 5, "limit": 10}},
  "results": [
    {
      "elevation": 661.1,
      "mindate": "1893-01-01",
      "maxdate": "2024-11-15",
      "latitude": 35.5951,
      "name": "ASHEVILLE REGIONAL AIRPORT, NC US",
      "datacoverage": 1,
      "id": "GHCND:USW00013874",
      "elevationUnit": "METERS",
      "longitude": -82.5572
    }
  ]
}

5. Locations & Location Categories

GET /locations
GET /locations/{id}
GET /locationcategories
GET /locationcategories/{id}

Browse location hierarchies (countries, states, cities, zip codes, climate regions).

Example:

curl -H "Token: YOUR_TOKEN" \
  "https://www.ncdc.noaa.gov/cdo-web/api/v2/locations?locationcategoryid=ST&limit=52"

Location category IDs: CITY, CLIM_DIV, CLIM_REG, CNTRY, CNTY, HYD_ACC, HYD_CAT, HYD_REG, HYD_SUB, ST, ZIP.

Workflow: Finding and Querying Data

1. Find a dataset: GET /datasets to list available datasets.
2. Find a station: GET /stations?datasetid=GHCND&locationid=ZIP:28801 to find nearby stations.
3. Check available data types: GET /datatypes?datasetid=GHCND&stationid=GHCND:USW00013874.
4. Query data: GET /data?datasetid=GHCND&stationid=GHCND:USW00013874&datatypeid=TMAX,TMIN&startdate=2024-01-01&enddate=2024-12-31&units=metric&limit=1000.

Notes

• The /data endpoint enforces a 1-year max date range per request. For multi-year queries, make sequential requests.
• Pagination: offset is 1-based. Loop until offset + limit > count from the metadata.
• Station IDs include a dataset prefix (e.g. GHCND:USW00013874).
• The attributes field in data results contains quality flags (comma-separated). Consult dataset documentation for flag meanings.
• Token goes in the header, not as a query parameter.

For /data, bound daily/subdaily requests to one year; monthly and annual datasets allow up to ten years. Follow the returned resultset offset and count rather than assuming every endpoint starts at the same offset. Official contract: https://www.ncei.noaa.gov/cdo-web/webservices/v2