Examples

This page contains practical examples of using the NOAA Climate API client.

Example 1: Temperature Analysis

Get daily high and low temperatures for a location:

from noaa import NOAA
from datetime import datetime, timedelta

client = NOAA("your-api-token")

# Get data for the past 30 days
end_date = datetime.now()
start_date = end_date - timedelta(days=30)

data = client.get_data(
    dataset_id="GHCND",
    station_id="GHCND:USW00094728",  # Central Park, NYC
    start_date=start_date.strftime("%Y-%m-%d"),
    end_date=end_date.strftime("%Y-%m-%d"),
    data_type_id=["TMAX", "TMIN"],
    units="metric"
)

# Process the data
temps = {}
for record in data['results']:
    date = record['date'][:10]
    if date not in temps:
        temps[date] = {}
    temps[date][record['datatype']] = record['value'] / 10  # Convert to Celsius

# Print results
for date in sorted(temps.keys()):
    if 'TMAX' in temps[date] and 'TMIN' in temps[date]:
        print(f"{date}: High {temps[date]['TMAX']}°C, Low {temps[date]['TMIN']}°C")

Example 2: Precipitation Data

Get precipitation data for multiple stations:

from noaa import NOAA

client = NOAA("your-api-token")

# Find stations in a state
stations = client.get_stations(
    dataset_id="GHCND",
    location_id="FIPS:06",  # California
    data_type_id="PRCP",
    limit=10
)

station_ids = [s['id'] for s in stations['results']]

# Get precipitation data
data = client.get_data(
    dataset_id="GHCND",
    station_id=station_ids,
    start_date="2023-01-01",
    end_date="2023-12-31",
    data_type_id="PRCP",
    units="metric"
)

# Calculate total precipitation per station
precip_by_station = {}
for record in data['results']:
    station = record['station']
    value = record['value'] / 10  # Convert to mm
    precip_by_station[station] = precip_by_station.get(station, 0) + value

for station, total in precip_by_station.items():
    print(f"{station}: {total:.1f} mm")

Example 3: Geographic Search

Find weather stations within a bounding box:

from noaa import NOAA

client = NOAA("your-api-token")

# Define bounding box for San Francisco Bay Area
# Format: minLat, minLon, maxLat, maxLon
extent = "37.0,-123.0,38.5,-121.5"

stations = client.get_stations(
    dataset_id="GHCND",
    extent=extent,
    limit=50
)

print(f"Found {len(stations['results'])} stations:")
for station in stations['results']:
    print(f"  {station['name']}")
    print(f"    Location: {station['latitude']}, {station['longitude']}")
    print(f"    Elevation: {station['elevation']} m")
    print(f"    Data coverage: {station['datacoverage']}")
    print()

Example 4: Data Type Discovery

Find available data types for a dataset:

from noaa import NOAA

client = NOAA("your-api-token")

# Get all data types for GHCND dataset
data_types = client.get_data_types(
    dataset_id="GHCND",
    limit=100
)

# Filter for temperature-related types
temp_types = [
    dt for dt in data_types['results']
    if 'temp' in dt['name'].lower()
]

print("Temperature data types:")
for dt in temp_types:
    print(f"  {dt['id']}: {dt['name']}")

Example 5: Pagination Through Large Results

Retrieve all stations for a dataset using pagination:

from noaa import NOAA

client = NOAA("your-api-token")

all_stations = []
offset = 0
limit = 1000

while True:
    response = client.get_stations(
        dataset_id="GHCND",
        location_id="FIPS:37",  # North Carolina
        limit=limit,
        offset=offset
    )

    stations = response['results']
    all_stations.extend(stations)

    # Check if we got all results
    metadata = response.get('metadata', {}).get('resultset', {})
    count = metadata.get('count', 0)

    if len(all_stations) >= count:
        break

    offset += limit

print(f"Retrieved {len(all_stations)} total stations")

Example 6: Date Range with Datetime Objects

Use datetime objects for date parameters:

from noaa import NOAA
from datetime import datetime, timedelta

client = NOAA("your-api-token")

# Define date range
end = datetime.now()
start = end - timedelta(days=7)  # Last 7 days

data = client.get_data(
    dataset_id="GHCND",
    station_id="GHCND:USW00094728",
    start_date=start,  # Pass datetime object
    end_date=end,      # Pass datetime object
    data_type_id="TMAX"
)

Example 7: Export to CSV

Export climate data to a CSV file:

from noaa import NOAA
import csv

client = NOAA("your-api-token")

data = client.get_data(
    dataset_id="GHCND",
    station_id="GHCND:USW00094728",
    start_date="2023-01-01",
    end_date="2023-12-31",
    data_type_id=["TMAX", "TMIN", "PRCP"],
    limit=1000
)

# Write to CSV
with open('climate_data.csv', 'w', newline='') as csvfile:
    fieldnames = ['date', 'station', 'datatype', 'value']
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

    writer.writeheader()
    for record in data['results']:
        writer.writerow({
            'date': record['date'],
            'station': record['station'],
            'datatype': record['datatype'],
            'value': record['value']
        })

print("Data exported to climate_data.csv")

Example 8: Working with Location Categories

Explore different types of locations:

from noaa import NOAA

client = NOAA("your-api-token")

# Get all location categories
categories = client.get_location_categories()

print("Available location categories:")
for cat in categories['results']:
    print(f"  {cat['id']}: {cat['name']}")

# Get locations for a specific category
states = client.get_locations(
    location_category_id="ST",
    limit=50
)

print("\nStates:")
for state in states['results']:
    print(f"  {state['name']}: {state['id']}")

Example 9: Monthly Summaries

Get monthly summary data:

from noaa import NOAA

client = NOAA("your-api-token")

# Get monthly data (GSOM dataset)
data = client.get_data(
    dataset_id="GSOM",
    station_id="GHCND:USW00094728",
    start_date="2023-01-01",
    end_date="2023-12-31",
    data_type_id=["TAVG", "PRCP"]
)

print("Monthly summaries:")
for record in data['results']:
    date = record['date']
    dtype = record['datatype']
    value = record['value']

    if dtype == "TAVG":
        print(f"{date}: Avg Temp = {value/10}°C")
    elif dtype == "PRCP":
        print(f"{date}: Total Precip = {value/10}mm")

Example 10: Comparing Multiple Locations

Compare climate data across different locations:

from noaa import NOAA
from collections import defaultdict

client = NOAA("your-api-token")

# Define stations to compare
stations = {
    "New York": "GHCND:USW00094728",
    "Los Angeles": "GHCND:USW00023174",
    "Chicago": "GHCND:USW00094846"
}

# Get data for all stations
data = client.get_data(
    dataset_id="GHCND",
    station_id=list(stations.values()),
    start_date="2023-07-01",
    end_date="2023-07-31",
    data_type_id="TMAX"
)

# Calculate average max temperature per station
temps = defaultdict(list)
for record in data['results']:
    station_id = record['station']
    temps[station_id].append(record['value'] / 10)

# Print results
print("Average July Maximum Temperature:")
station_lookup = {v: k for k, v in stations.items()}
for station_id, values in temps.items():
    city = station_lookup.get(station_id, station_id)
    avg_temp = sum(values) / len(values)
    print(f"  {city}: {avg_temp:.1f}°C")