Title: Accessing NOAA Climate Data Online
Version: 1.0.0
Author: Steph Buongiorno [aut, cre]
Maintainer: Steph Buongiorno <steph.buon@proton.me>
Description: Fetch data from the National Oceanic and Atmospheric Administration Climate Data Online (NOAA CDO) https://www.ncdc.noaa.gov/cdo-web/webservices/v2 API including daily, monthly, and yearly climate summaries, radar data, climatological averages, precipitation data, annual summaries, storm events, and agricultural meteorology.
License: GPL-3
Encoding: UTF-8
Imports: httr, jsonlite
RoxygenNote: 7.3.2
NeedsCompilation: no
Packaged: 2025-05-12 22:43:51 UTC; steph
Repository: CRAN
Date/Publication: 2025-05-14 08:50:02 UTC

Retrieve Climate Data from the NOAA API

Description

Queries the NOAA Climate Data Online (CDO) API to retrieve climate data for a given dataset, station or location, and date range. Supports automatic pagination to collect large datasets.

Usage

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

Arguments

noaa_token

A character string. Your NOAA API token used for authentication. You can request a token at https://www.ncdc.noaa.gov/cdo-web/token.

datasetid

A valid dataset ID (e.g., "GHCND", "GSOM", "GSOY"). Use valid_ids() to view supported datasets.

stationid

Optional. A NOAA station ID (e.g., "GHCND:USW00094728"). Required for most station-based datasets.

locationid

Optional. A NOAA location ID (e.g., "FIPS:37", "CITY:US390029"). Used for location-based datasets.

startdate

Start date (YYYY-MM-DD) for the query range.

enddate

End date (YYYY-MM-DD) for the query range.

n_results

Maximum number of results to retrieve. Defaults to Inf (all available results).

Value

A data frame of climate data observations returned by the NOAA API.

Examples

if (nzchar(Sys.getenv("NOAA_TOKEN"))) {
  # Set your NOAA token
  noaa_token <- Sys.getenv("NOAA_TOKEN")

  # Example request: Daily summaries from Central Park, NY (GHCND:USW00094728)
  data <- get_climate_data(
    noaa_token = noaa_token,
    datasetid = "GHCND",
    stationid = "USW00094728",
    startdate = "2020-01-01",
    enddate = "2020-01-31"
  )
  head(data)
}

Retrieve NOAA Location IDs for a Given Category

Description

Queries the NOAA Climate Data Online (CDO) API to retrieve location identifiers for a specified category (e.g., state, city, county).

Usage

get_locationid(noaa_token, category_id, n_results = Inf)

Arguments

noaa_token

A character string. Your NOAA API token used for authentication. You can request a token at https://www.ncdc.noaa.gov/cdo-web/token.

category_id

A valid location category ID. Options: "ST", "CITY", "COUNTY", "ZIP", "CLIM_REG", "HYDROL_REG", "FIPS".

n_results

Maximum number of results to retrieve. Defaults to Inf (all results).

Value

A data frame of location IDs matching the given category.

Examples

if (nzchar(Sys.getenv("NOAA_TOKEN"))) {
  # Retrieve token from environment variable
  noaa_token <- Sys.getenv("NOAA_TOKEN")

  # Get all U.S. state-level location IDs using category "FIPS"
  locations <- get_locationid(noaa_token = noaa_token, category_id = "FIPS")
  head(locations)
}

Retrieve Station IDs for a Given Dataset and Location

Description

Queries the NOAA Climate Data Online (CDO) API to retrieve station identifiers associated with a specified dataset, location, and date range.

Usage

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

Arguments

noaa_token

A character string. Your NOAA API token used for authentication. You can request a token at https://www.ncdc.noaa.gov/cdo-web/token.

datasetid

A valid dataset ID (e.g., "GHCND", "GSOM", etc.). Use valid_ids() to see supported values.

locationid

Optional. A valid location ID (e.g., "FIPS:37", "CITY:US390029"). If NULL, all locations are considered.

startdate

Start date (YYYY-MM-DD) for station data coverage.

enddate

End date (YYYY-MM-DD) for station data coverage.

n_results

Maximum number of station results to retrieve. Defaults to Inf to fetch all available.

Value

A data frame containing metadata for the matching NOAA stations.

Examples

if (nzchar(Sys.getenv("NOAA_TOKEN"))) {
  # Retrieve your NOAA API token from environment
  noaa_token <- Sys.getenv("NOAA_TOKEN")

  # Get stations for the GHCND dataset in Texas between 2020-01-01 and 2020-12-31
  stations <- get_stationid(
    noaa_token = noaa_token,
    datasetid = "GHCND",
    locationid = "FIPS:48",
    startdate = "2020-01-01",
    enddate = "2020-12-31"
  )
  head(stations)
}