← Về thư mục

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)

Parameter	Type	Required	Default	Description
datasetid	string	Varies	-	Dataset ID (e.g. GHCND, GSOM).
datatypeid	string	No	-	Data type filter (e.g. TMAX, PRCP).
locationid	string	No	-	Location ID (e.g. FIPS:37, ZIP:28801, CITY:US390029).
stationid	string	No	-	Station ID (e.g. GHCND:USW00013874).
startdate	string	Varies	-	ISO date YYYY-MM-DD.
enddate	string	Varies	-	ISO date YYYY-MM-DD.
units	string	No	standard	standard or metric.
limit	int	No	25	Results per page (max 1000).
offset	int	No	1	Pagination offset (1-based).
sortfield	string	No	-	Field to sort by (e.g. date, name).
sortorder	string	No	asc	asc or desc.

---

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
    }
  ]
}

Note: When units=standard, GHCND temperature values are in tenths of degrees C. With units=metric, they are converted to degrees C.

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: | ID | Name | Description | |----------|------|-------------| | GHCND | Daily Summaries | Global daily station observations (TMAX, TMIN, PRCP, SNOW, etc.) | | GSOM | Global Summary of the Month | Monthly aggregates | | GSOY | Global Summary of the Year | Annual aggregates | | NORMAL_DLY | Climate Normals Daily | 30-year daily normals | | NORMAL_MLY | Climate Normals Monthly | 30-year monthly normals | | PRECIP_15 | Precipitation 15-Minute | Sub-hourly precipitation | | PRECIP_HLY | Precipitation Hourly | Hourly precipitation |

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: | ID | Description | |--------|-------------| | TMAX | Maximum temperature | | TMIN | Minimum temperature | | TAVG | Average temperature | | PRCP | Precipitation | | SNOW | Snowfall | | SNWD | Snow depth | | AWND | Average wind speed | | WSF2 | Fastest 2-minute wind speed |

4. Stations

GET /stations
GET /stations/{id}

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

Additional Parameters: | Parameter | Type | Description | |-----------|--------|-------------| | extent | string | Bounding box: south_lat,west_lon,north_lat,east_lon. |

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.