Title: Access 'NOAA' Climate and Weather Data
Version: 0.1.1
Description: Provides clean, tidy access to climate and weather data from the 'National Oceanic and Atmospheric Administration' ('NOAA') via the 'National Centers for Environmental Information' ('NCEI') Data Service API https://www.ncei.noaa.gov/access/services/data/v1. Covers daily weather observations, monthly and annual summaries, and 30-year climate normals from over 100,000 stations across 180 countries. No API key is required. Dedicated functions handle the most common datasets, while a generic fetcher provides access to all 'NCEI' datasets. Station discovery functions help users find stations by location or name. Data is downloaded on first use and cached locally for subsequent calls. This package is not endorsed or certified by 'NOAA'.
License: MIT + file LICENSE
Encoding: UTF-8
Language: en-US
URL: https://github.com/charlescoverdale/readnoaa
BugReports: https://github.com/charlescoverdale/readnoaa/issues
RoxygenNote: 7.3.3
Depends: R (≥ 4.1.0)
Imports: cli (≥ 3.6.0), httr2 (≥ 1.0.0), tools
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-03-16 17:54:01 UTC; charlescoverdale
Author: Charles Coverdale [aut, cre, cph]
Maintainer: Charles Coverdale <charlesfcoverdale@gmail.com>
Repository: CRAN
Date/Publication: 2026-03-19 15:00:02 UTC

readnoaa: Access 'NOAA' Climate and Weather Data

Description

Provides clean, tidy access to climate and weather data from the 'National Oceanic and Atmospheric Administration' ('NOAA') via the 'National Centers for Environmental Information' ('NCEI') Data Service API https://www.ncei.noaa.gov/access/services/data/v1. Covers daily weather observations, monthly and annual summaries, and 30-year climate normals from over 100,000 stations across 180 countries. No API key is required. Dedicated functions handle the most common datasets, while a generic fetcher provides access to all 'NCEI' datasets. Station discovery functions help users find stations by location or name. Data is downloaded on first use and cached locally for subsequent calls. This package is not endorsed or certified by 'NOAA'.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com [copyright holder]

See Also

Useful links:

Clear the readnoaa cache

Description

Deletes all locally cached NOAA data files. The next call to any data function will re-download from the NCEI API.

Usage

clear_cache()

Value

Invisible NULL.

See Also

Other data access: list_datasets(), list_datatypes(), noaa_get()

Examples


op <- options(readnoaa.cache_dir = tempdir())
clear_cache()
options(op)

List common NCEI datasets

Description

Returns a curated table of the most commonly used NCEI datasets. No network call is made.

Usage

list_datasets()

Value

A data frame with columns:

dataset

Character. Dataset identifier for use with noaa_get().

description

Character. Brief description.

frequency

Character. Temporal resolution.

See Also

Other data access: clear_cache(), list_datatypes(), noaa_get()

Examples

list_datasets()

List available data types for a dataset

Description

Queries the NCEI API to discover what data types (variables) are available for a given dataset and station. This makes a short data request to identify available columns.

Usage

list_datatypes(dataset, station, cache = TRUE)

Arguments

dataset

Character. Dataset identifier (e.g. "daily-summaries").

station

Character. A station ID to query.

cache

Logical. Use cached data if available (default TRUE).

Value

A character vector of available data type codes.

See Also

Other data access: clear_cache(), list_datasets(), noaa_get()

Examples


op <- options(readnoaa.cache_dir = tempdir())
list_datatypes("daily-summaries", "USW00094728")
options(op)

Annual weather summaries

Description

Returns annual summary data from the NCEI Global Summary of the Year dataset.

Usage

noaa_annual(
  station,
  start_date,
  end_date,
  datatypes = NULL,
  units = "metric",
  include_flags = FALSE,
  include_location = FALSE,
  cache = TRUE
)

Arguments

station

Character. One or more station IDs.

start_date

Character. Start date in "YYYY-MM-DD" or "YYYY-MM" format.

end_date

Character. End date in the same format.

datatypes

Optional character vector of data type codes.

units

Character. "metric" (default) or "standard".

include_flags

Logical. Include data quality flags from NCEI (default FALSE).

include_location

Logical. Include station latitude, longitude, and elevation columns (default FALSE).

cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns including:

station

Character. Station identifier.

date

Date. First day of the year.

name

Character. Station name.

...

Numeric. Data columns vary by station and request.

See Also

Other weather data: noaa_daily(), noaa_monthly(), noaa_normals()

Examples


op <- options(readnoaa.cache_dir = tempdir())
noaa_annual("USW00094728", "2020-01-01", "2024-01-01")
options(op)

Daily weather observations

Description

Returns daily weather data from the NCEI Daily Summaries dataset (GHCN-Daily). Common data types include TMAX (maximum temperature), TMIN (minimum temperature), PRCP (precipitation), SNOW (snowfall), and SNWD (snow depth).

Usage

noaa_daily(
  station,
  start_date,
  end_date,
  datatypes = NULL,
  units = "metric",
  include_flags = FALSE,
  include_location = FALSE,
  cache = TRUE
)

Arguments

station

Character. One or more station IDs (e.g. "USW00094728" for Central Park, NYC).

start_date

Character. Start date in "YYYY-MM-DD" or "YYYY-MM" format.

end_date

Character. End date in the same format.

datatypes

Optional character vector of data type codes to retrieve (e.g. c("TMAX", "TMIN")). If NULL, all available types are returned.

units

Character. "metric" (default, Celsius/mm) or "standard" (Fahrenheit/inches).

include_flags

Logical. Include data quality flags from NCEI (default FALSE).

include_location

Logical. Include station latitude, longitude, and elevation columns (default FALSE).

cache

Logical. Use cached data if available (default TRUE).

Details

Requests spanning more than one year are automatically split into yearly chunks to avoid API timeouts.

Value

A data frame with columns including:

station

Character. Station identifier.

date

Date. Observation date.

name

Character. Station name.

...

Numeric. Data columns vary by station and request (e.g. tmax, tmin, prcp).

See Also

Other weather data: noaa_annual(), noaa_monthly(), noaa_normals()

Examples


op <- options(readnoaa.cache_dir = tempdir())
# Daily temperatures for Central Park, NYC
noaa_daily("USW00094728", "2024-01-01", "2024-01-31",
           datatypes = c("TMAX", "TMIN"))
options(op)

Fetch any NCEI dataset

Description

A generic fetcher for direct access to any NCEI dataset. Use list_datasets() to see common dataset identifiers.

Usage

noaa_get(
  dataset,
  station = NULL,
  start_date = NULL,
  end_date = NULL,
  datatypes = NULL,
  bbox = NULL,
  units = "metric",
  include_flags = FALSE,
  include_location = FALSE,
  cache = TRUE
)

Arguments

dataset

Character. The dataset identifier (e.g. "daily-summaries", "global-summary-of-the-month").

station

Optional character vector of station IDs.

start_date

Optional start date in "YYYY-MM-DD" or "YYYY-MM" format.

end_date

Optional end date in the same format.

datatypes

Optional character vector of data type codes.

bbox

Optional numeric vector of length 4 defining a bounding box: c(south_lat, west_lon, north_lat, east_lon).

units

Character. "metric" (default) or "standard".

include_flags

Logical. Include data quality flags from NCEI (default FALSE).

include_location

Logical. Include station latitude, longitude, and elevation columns (default FALSE).

cache

Logical. Use cached data if available (default TRUE).

Value

A data frame. Columns vary by dataset.

See Also

Other data access: clear_cache(), list_datasets(), list_datatypes()

Examples


op <- options(readnoaa.cache_dir = tempdir())
# Fetch daily data using the generic function
noaa_get("daily-summaries", station = "USW00094728",
         start_date = "2024-01-01", end_date = "2024-01-31")
options(op)

Monthly weather summaries

Description

Returns monthly summary data from the NCEI Global Summary of the Month dataset.

Usage

noaa_monthly(
  station,
  start_date,
  end_date,
  datatypes = NULL,
  units = "metric",
  include_flags = FALSE,
  include_location = FALSE,
  cache = TRUE
)

Arguments

station

Character. One or more station IDs.

start_date

Character. Start date in "YYYY-MM-DD" or "YYYY-MM" format.

end_date

Character. End date in the same format.

datatypes

Optional character vector of data type codes.

units

Character. "metric" (default) or "standard".

include_flags

Logical. Include data quality flags from NCEI (default FALSE).

include_location

Logical. Include station latitude, longitude, and elevation columns (default FALSE).

cache

Logical. Use cached data if available (default TRUE).

Value

A data frame with columns including:

station

Character. Station identifier.

date

Date. First day of the month.

name

Character. Station name.

...

Numeric. Data columns vary by station and request.

See Also

Other weather data: noaa_annual(), noaa_daily(), noaa_normals()

Examples


op <- options(readnoaa.cache_dir = tempdir())
noaa_monthly("USW00094728", "2024-01", "2024-12")
options(op)

Find stations near a location

Description

Searches for weather stations within a given radius of a point, sorted by distance. Uses the GHCN-Daily station inventory.

Usage

noaa_nearby(lat, lon, radius_km = 50, limit = 25L)

Arguments

lat

Numeric. Latitude of the target location.

lon

Numeric. Longitude of the target location.

radius_km

Numeric. Search radius in kilometres (default 50).

limit

Integer. Maximum number of results (default 25).

Value

A data frame with the same columns as noaa_stations() plus:

distance_km

Numeric. Distance from the target point in kilometres.

See Also

Other station discovery: noaa_stations()

Examples


op <- options(readnoaa.cache_dir = tempdir())
# Stations within 25 km of central London
noaa_nearby(51.5, -0.1, radius_km = 25)
options(op)

Climate normals (1991-2020)

Description

Returns 30-year climate normals from the NCEI Normals dataset. Normals represent the average climate conditions over the 1991-2020 period.

Usage

noaa_normals(
  station,
  period = "monthly",
  datatypes = NULL,
  include_flags = FALSE,
  include_location = FALSE,
  cache = TRUE
)

Arguments

station

Character. One or more station IDs.

period

Character. One of "monthly", "daily", or "annual".

datatypes

Optional character vector of data type codes.

include_flags

Logical. Include data quality flags from NCEI (default FALSE).

include_location

Logical. Include station latitude, longitude, and elevation columns (default FALSE).

cache

Logical. Use cached data if available (default TRUE).

Value

A data frame. Columns vary by period but typically include station, date or month, and normal values for temperature, precipitation, and other variables.

See Also

Other weather data: noaa_annual(), noaa_daily(), noaa_monthly()

Examples


op <- options(readnoaa.cache_dir = tempdir())
noaa_normals("USW00094728", "monthly")
options(op)

Search for weather stations

Description

Searches the GHCN-Daily station inventory by bounding box or text query. The station list (~120,000 stations worldwide) is downloaded once and cached locally.

Usage

noaa_stations(bbox = NULL, text = NULL, limit = 25L, cache = TRUE)

Arguments

bbox

Optional numeric vector of length 4 defining a bounding box: c(south_lat, west_lon, north_lat, east_lon).

text

Optional character string to search station names (case-insensitive).

limit

Integer. Maximum number of results (default 25).

cache

Logical. Use cached station list if available (default TRUE).

Value

A data frame with columns:

station

Character. Station identifier.

name

Character. Station name.

latitude

Numeric. Latitude in decimal degrees.

longitude

Numeric. Longitude in decimal degrees.

elevation

Numeric. Elevation in metres.

See Also

Other station discovery: noaa_nearby()

Examples


op <- options(readnoaa.cache_dir = tempdir())
# Search for stations in London area
noaa_stations(bbox = c(51.3, -0.5, 51.7, 0.3))

# Search by name
noaa_stations(text = "Heathrow")
options(op)