Skip to content

Global Summary of the Year

Available since v0.10.0 as noaa:gsoy. GSOY uses the anonymous NCEI Access Data Service dataset global-summary-of-the-year, reusing GHCN/GSOM station discovery, pagination, and 50-station CSV chunks. Require both dates and either stations or a location/bbox, not both. units is metric (default) or standard; unknown parameters and text queries are rejected.

Every UTC calendar year touched by the interval is selected in full: May 6–7 selects the whole year; December 31–January 1 selects both years. Search and data requests use January 1 through December 31, giving equivalent year selections identical URLs and asset IDs. Asset coverage labels complete years; the original query remains in the manifest. A timezone offset can change the selected UTC year.

CSV DATE is a four-digit year. Use item.open_csv(dtype={"DATE": "string"}) to preserve it as text with the existing pandas reader. Common variables are PRCP (annual precipitation total, metric millimeters) and TAVG (annual mean temperature, metric degrees Celsius). CSV contains no units row; the frame's attrs["usdata"]["properties"]["units"] records the requested unit system. Variable availability depends on the station.

Some elements, including degree-day summaries, have hemisphere-dependent accumulation seasons. Annual record labels do not mean every element represents January–December observations. Consult the GSOY field documentation. Dataset metadata describes global GHCN-Daily-derived summaries and weekly updates. Revisions can change CSV bytes; retain the cache as well as the manifest and lockfile.

See the service research notes for dated upstream probes.

Metadata sources

Every value in the catalog entry's resolution, cadence, citation, terms, variables, and limits comes from one of these pages. A field the agency does not publish is left empty rather than estimated.

  • Updates, citation, and terms: the NCEI dataset record, which states weekly updates and the Lawrimore et al. (2016) citation with its DOI.
  • Resolution and variables: the same record and the element codes this guide names, with the units the Access Data Service returns under units=metric. The element set is open and station-dependent.
  • Latency is empty: the record states no lag between a year's end and its summary.

All NOAA datasets.

Reference

noaa:gsoy · Released · Included since usdata 0.10. Global Summary of the Year.

At a glance

  • Files: CSV
  • Selection: Complete UTC calendar years touched by the query; station and element filters
  • Required inputs: Both dates; station IDs or a geographic query
  • Open locally: usdata[pandas] · Reader guide
  • On usdata.dev: Annual station climate, with a walkthrough

Parameters

Pass these as --param name=value to the CLI, as params: entries in a manifest, or as keyword arguments to build_query.

Parameter Meaning
stations Station ids, comma-separated or a list; otherwise a location selects them.
units metric (default) or standard.

Variables

Variable Units Meaning
PRCP mm Annual precipitation total (metric units)
TAVG degrees Celsius Annual mean temperature (metric units)

Catalog facts

  • Availability: since 0.10
  • Domain: Surface weather
  • Spatial resolution: Land surface stations, derived from GHCN-Daily
  • Temporal resolution: Annual
  • Updates: Weekly
  • Terms of use: https://www.ncei.noaa.gov/metadata/geoportal/rest/metadata/item/gov.noaa.ncdc:C00947/html
  • Citation: Lawrimore, Jay H.; Ray, Ron; Applequist, Scott; Korzeniewski, Bryant; Menne, Matthew J. (2016): Global Summary of the Year (GSOY), Version 1. NOAA National Centers for Environmental Information. https://doi.org/10.7289/JWPF-Y430
  • Geographic bounds (WGS84): west -180°, south -90°, east 180°, north 90°
  • Coverage varies by station, product, and date; the range above does not guarantee observations.
  • Upstream documentation
  • License: US Government Work (public domain)
  • Transport: http
  • Adapter: usdata.providers.noaa.gsoy:GlobalSummaryYearly