act.discovery.get_asos_data#

act.discovery.get_asos_data(time_window, lat_range=None, lon_range=None, station=None, regions=None, variables=None)[source]#

Retrieve ASOS observations from the Iowa Environmental Mesonet.

Data can be requested either by station identifier, geographic bounds, or region.

Parameters:

time_window (tuple) – Two-member sequence containing the start and end times as Python datetime objects.
lat_range (tuple, optional) – Latitude range (min_latitude, max_latitude) used to discover ASOS stations.
lon_range (tuple, optional) – Longitude range (min_longitude, max_longitude) used to discover ASOS stations.
station (str or sequence of str, optional) – One station identifier or a sequence of station identifiers. Examples: "ORD" or ["ORD", "MDW", "DPA"].
regions (str or sequence of str, optional) – Region/network identifiers. Examples: "IL" or ["IL", "WI", "IN"]. Regions can be used alone to retrieve all stations in the requested region(s), or together with latitude and longitude bounds to narrow geographic station discovery.
variables (sequence of str, optional) – IEM ASOS variables to request. If omitted, data=all is used.

Returns:

asos_ds (dict of xarray.Dataset) – Dictionary keyed by ASOS station identifier.

Examples

Retrieve data for a single ASOS station.

from datetime import datetime

import act

time_window = [
    datetime(2020, 2, 4, 2, 0),
    datetime(2020, 2, 4, 4, 0),
]

asos = act.discovery.get_asos_data(
    time_window,
    station="ORD",
)

Retrieve multiple ASOS stations in a single request.

asos = act.discovery.get_asos_data(
    time_window,
    station=["ORD", "MDW", "DPA"],
)

Retrieve all available ASOS stations within a latitude and longitude bounding box.

lat_range = (41.3, 42.3)
lon_range = (-88.2, -87.1)

asos = act.discovery.get_asos_data(
    time_window,
    lat_range=lat_range,
    lon_range=lon_range,
)

Retrieve all available ASOS stations from a region.

asos = act.discovery.get_asos_data(
    time_window,
    regions="IL",
)

Multiple regions can also be requested.

asos = act.discovery.get_asos_data(
    time_window,
    regions=["IL", "IN", "WI"],
)

Limit the request to selected ASOS variables.

asos = act.discovery.get_asos_data(
    time_window,
    station="ORD",
    variables=["tmpf", "dwpf", "relh", "drct", "sknt"],
)

Regions can optionally be combined with a geographic bounding box to limit station discovery to selected IEM networks.

asos = act.discovery.get_asos_data(
    time_window,
    lat_range=lat_range,
    lon_range=lon_range,
    regions=["IL", "IN"],
)

Notes

Explicit station requests do not require metadata-network lookups. Latitude, longitude, and elevation are requested directly from the ASOS endpoint.

Geographic requests do not require regions. When regions is not supplied, ACT uses a single global IEM METAR/ASOS metadata request and filters stations by latitude/longitude. Supplying regions alone retrieves all stations in those regional networks. Large station sets are automatically split into smaller batched ASOS requests.

Code was updated using ChatGPT following testing and feedback from the developer. Code was reviewed and tested by the developer before the PR.