Skip to contents

noaa: Accessing Current and Historic Weather Data by NOAA

National Oceanic and Atmospheric Administration (NOAA) maintains one of the largest climate data archives, the National Climatic Data Center (NCDC). NCDC’s Climate Data Online (CDO) offers web services that provide access to weather and climate data, which include (but is not limited to) minimum and maximum temperature in different zip codes by date, amount of precipitation, longitude and latitude of stations, and more.

It is the only known R package that enables the user to search historical weather data by zip code.

Install

Install from CRAN:

install.packages("noaa")

Install from rOpenGov:

options(repos = c(
    ropengov = "https://ropengov.r-universe.dev",
    CRAN = "https://cloud.r-project.org"))

install.packages("noaa")

Authentication Token

Accessing CDO data requires a token.

Get a token by going to www.ncdc.noaa.gov/cdo-web/token and entering your email address.

get_climate_data()

The get_climate_data() function allows you to retrieve climate and weather data from the NOAA Climate Data Online (CDO) API for a wide range of dataset types. It supports pagination and can retrieve large numbers of records by iteratively querying the API.

Function Overview 

get_climate_data(noaa_token, datasetid, stationid = NULL, locationid = NULL, startdate, enddate, n_results = Inf)

Arguments

Argument Type Description
noaa_token string Your NOAA API token, available by registering at NOAA CDO.
datasetid string The dataset identifier. Must be one of the valid NOAA dataset IDs (see below).
stationid string or NULL The station ID (e.g., "USW00094728"). Required for station-based datasets.
locationid string or NULL The location ID (e.g., "FIPS:48" for Texas). Required for location-based datasets.
startdate string Start date for the query in "YYYY-MM-DD" format.
enddate string End date for the query in "YYYY-MM-DD" format.
n_results numeric Maximum number of results to return. Use Inf (default) to fetch all available records.

Supported Dataset IDs

The function currently supports the following datasets:

  • GHCND – Daily summaries
  • GSOM – Monthly summaries
  • GSOY – Yearly summaries
  • NEXRAD2, NEXRAD3 – Radar data
  • NORMAL_DLY, NORMAL_MLY, ANN, ANNUAL – Climate normals
  • PRECIP_15, PRECIP_HLY – Precipitation data
  • ISD – Integrated Surface Data
  • CLIMDIV – Climate division data
  • CPC – Climate Prediction Center data
  • LCD – Local Climatological Data
  • AGRMET – Agricultural Meteorological data
  • STORM_EVENTS – Storm event data

Example 

# Example: Get daily precipitation for Central Park, NY in January 2020
df <- get_climate_data(
  noaa_token = "YOUR_API_KEY",
  datasetid = "GHCND",
  stationid = "USW00094728",
  startdate = "2020-01-01",
  enddate = "2020-01-31",
  n_results = 1000
)

get_locationid()

The get_locationid() function retrieves location identifiers from the NOAA Climate Data Online (CDO) API based on a specified category. It supports pagination to return large sets of location data.

Function Overview 

get_locationid(noaa_token, category_id, n_results = Inf)

Arguments

Argument Type Description
noaa_token string NOAA API token used for authentication.
category_id string The location category identifier. Must be one of the valid location categories (see below).
n_results numeric Maximum number of results to retrieve. Defaults to Inf to fetch all available records.

Supported Location Category IDs

The function supports the following location categories:

  • ST – U.S. States and territories (e.g., "ST:TX" for Texas)
  • CITY – Major U.S. cities with weather stations
  • COUNTY – U.S. counties (e.g., "COUNTY:US36061" for New York County, NY)
  • ZIP – ZIP Code areas
  • CLIM_REG – NOAA-defined climate regions (e.g., Southeast, Midwest)
  • HYDROL_REG – Hydrologic regions used for water resource planning
  • FIPS – Federal Information Processing Standards codes (e.g., "FIPS:37" for North Carolina)

Example 

# Example: Retrieve a list of U.S. states
df <- get_locationid(
  noaa_token = "YOUR_API_KEY",
  category_id = "ST",
  n_results = 100
)

Returns

A data frame containing location metadata from the specified category. If no results are returned or the request fails, an error is thrown or an empty data frame is returned.

get_stationid()

The get_stationid() function retrieves weather station metadata from the NOAA Climate Data Online (CDO) API for a given dataset and time range. It supports pagination and can return a large number of station records.

Function Overview 

get_stationid(noaa_token, datasetid, locationid = NULL, startdate, enddate, n_results = Inf)

Arguments

Argument Type Description
noaa_token string NOAA API token used for authentication.
datasetid string The dataset identifier. Must be one of the valid dataset IDs (see list used by valid_ids()).
locationid string or NULL Optional location identifier to filter stations geographically (e.g., "FIPS:48" for Texas).
startdate string Start date in "YYYY-MM-DD" format.
enddate string End date in "YYYY-MM-DD" format.
n_results numeric Maximum number of station records to retrieve. Defaults to Inf to fetch all.

Example 

# Example: Get stations in Texas for the GHCND dataset during 2020
df <- get_stationid(
  noaa_token = "YOUR_API_KEY",
  datasetid = "GHCND",
  locationid = "FIPS:48",
  startdate = "2020-01-01",
  enddate = "2020-12-31",
  n_results = 1000
)

Returns

A data frame containing weather station metadata, such as station IDs, names, geographic coordinates, and available coverage. If no results are returned or the request fails, an error is thrown or an empty data frame is returned.

A detailed list of NOAA acronyms can be found here: https://www1.ncdc.noaa.gov/pub/data/ghcn/daily/readme.txt