aidweather

aidweather

Agroclimatic & Solar Data Integration from NASA POWER

aidweather bridges your project with reliable weather and solar radiation data from NASA's POWER API. Key features include:

1. Seamless NASA POWER Integration: Serves as a bridge between your application and NASA POWER weather services, hiding the complexities of constructing API requests, handling timeouts, and verifying payload structures.
2. Versatile Spatial Fetching: Flexible data retrieval across single points, 1D transect paths, and 2D regional bounding boxes, with internal tuning levers to ensure accurate and consistent spatial sampling.
3. SQLite Caching & API Compliance: Built-in SQLite caching prevents redundant downloads, saving bandwidth and avoiding unnecessary hits to NASA POWER servers while enforcing rate limits and data usage policies.
4. Python Bindings & Full CLI: Dual interface offering an intuitive Python API for data science workflows and a full-featured Command Line Interface (CLI) for quick command-line extractions.
5. Smart Error Catching & Logging: Comprehensive activity logging and intelligent error handling, providing clear insights into query execution and data processing.

Quick install (Python):

pip install aidweather

Quick install (CLI, via uv):

uv tool install aidweather

See Installation below for optional-extras and source/development install options (including the GitHub-based install scripts).

[!WARNING] Beta Status: aidweather is in active beta. Public API methods and CLI options are stable, but additions may occur prior to 1.0. Feedback and issue reports are welcome.

[!IMPORTANT] Data Provenance & Spatial Support: A coordinate submitted to NASA POWER resolves to a source product grid cell; it does not produce a point measurement at the precise coordinate. Different parameters originate from different source products (e.g. MERRA-2 at 0.5° × 0.625°, CERES solar radiation at 1.0° × 1.0°). Nearby coordinates mapping to the same source cell will return identical series.

---

Supported NASA POWER Parameters

aidweather includes built-in metadata, unit validation, and spatial grid specifications for 18 core weather, solar radiation, and soil moisture parameters:

— indicates the parameter is not published on NASA POWER's hourly endpoint; requesting it with temporal_api="hourly" raises ValueError.

---

Installation

PyPI (recommended)

pip install aidweather

Or, for the CLI as an isolated tool via uv:

uv tool install aidweather

From source / development install

The install scripts below clone from GitHub and are intended for development setups (editable install, dev tooling, the Claude Code skill) rather than everyday installation.

Unix / macOS:

curl -fsSL https://raw.githubusercontent.com/matiollipt/aidweather/main/install.sh | bash

Or install the latest unreleased main via uv tool:

uv tool install git+https://github.com/matiollipt/aidweather.git

Windows (PowerShell):

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/matiollipt/aidweather/main/install.ps1))) -Yes

Optional Extras

pyproject.toml defines two optional-dependency groups: test (pytest, ruff, mypy, and related type-checking/test tooling) and release (build, twine, for cutting a release per docs/release_checklist.md).

With uv tool install — append the extra(s) to the package spec, in brackets, before the @:

# Single extra
uv tool install "aidweather[test] @ git+https://github.com/matiollipt/aidweather.git"

# Multiple extras
uv tool install "aidweather[test,release] @ git+https://github.com/matiollipt/aidweather.git"

With the install scripts — pass --extra NAME (repeatable) on Unix/macOS or -Extra NAME on Windows; --dev/-Dev is a shortcut for both test and release:

# Unix / macOS
./install.sh --extra test              # test tooling only
./install.sh --dev                     # test + release (equivalent to --extra test --extra release)
curl -fsSL .../install.sh | bash -s -- --dev -y

# Windows (PowerShell)
.\install.ps1 -Extra test
.\install.ps1 -Dev

From a local clone, the same extras syntax works directly with pip/uv pip:

pip install -e ".[test]"
uv pip install -e ".[test,release]"

---

Claude Code Skill

aidweather ships a Claude Code skill (bundled as package data at src/aidweather/assets/skills/aidweather/) that teaches an agent how to bootstrap the CLI, translate messy coordinate/date requests into aidweather calls, and read back JSON output. Install it into ~/.claude/skills/aidweather alongside the package:

./install.sh --install-skill
# or, on an existing install, just re-run with the flag added:
./install.sh --install-skill -y

.\install.ps1 -InstallSkill

If you only want the skill (no package install), download the two files directly: SKILL.md and references/request-patterns.md, and place them under ~/.claude/skills/aidweather/.

---

Documentation Guides

The documentation is organized into dedicated guides for scientific users and developers:

• User Guide — Step-by-step introduction to fetching and analyzing weather data.
• Spatial Interpretation Guide — Understanding native grid resolutions, transects, regional boxes, and station comparisons.
• Parameter & Provenance Guide — Parameter catalogue, NASA source models, temporal availability, and time standards.
• Geospatial Coordinate Reference — Coordinate notation systems (DD, DDM, DMS), string parsing, and GeoCoordinate usage.
• DataFrame Date Utilities Reference — Date column matching, DatetimeIndex fallbacks, and timezone handling.
• API Reference — Complete Python API reference for PowerClient, GeoCoordinate, and query functions.
• Configuration Reference — Environment variables, JSON configuration assets, and SQLite cache settings.
• Developer Guide — Internal request lifecycles, cache key design, and architecture details.
• Contributing & Testing — Guidelines for contributing, running pytest, and checking typing with mypy.

---

Quick Start (Python)

from aidweather import PowerClient, GeoCoordinate

# Initialize client for daily temporal resolution
client = PowerClient(temporal_api="daily")

# 1. Fetch single-point meteorological and solar data
df = client.get_point_data(
    lat=-23.55,
    lon=-46.63,
    start="2023-01-01",
    end="2023-01-31",
    params=["T2M", "ALLSKY_SFC_SW_DWN", "PRECTOTCORR"],
)
print(df.head())

# 2. Sample along a 1D spatial transect (respecting native parameter grid spacing)
coord_a = GeoCoordinate.from_decimal(-25.0, -48.0)
coord_b = GeoCoordinate.from_decimal(-20.0, -48.0)

df_transect = client.get_transect_data(
    start_coord=coord_a,
    end_coord=coord_b,
    start="2023-01-01",
    end="2023-01-07",
    params=["T2M"],
    spacing_km=100.0,
)
print(df_transect.head())

---

Command Line Interface (CLI)

# Fetch single-point data to CSV
aidweather fetch --lat -23.55 --lon -46.63 \
    --start 2023-01-01 --end 2023-01-31 \
    --params T2M,PRECTOTCORR --output point_data.csv

# Sample along a 1D spatial transect
aidweather fetch-transect \
    --lat-start -25.0 --lon-start -48.0 \
    --lat-end   -20.0 --lon-end   -48.0 \
    --start 2023-01-01 --end 2023-01-31 \
    --spacing-km 100.0

# Fetch regional bounding box data (max 4.5° x 4.5°, 1 parameter per request)
aidweather fetch-regional --lat-min -23.5 --lat-max -20.0 \
    --lon-min -47.0 --lon-max -44.0 \
    --start 2023-01-01 --end 2023-01-31 \
    --params T2M --output regional.csv

# Inspect parameter metadata & local cache
aidweather params list --group all
aidweather params describe T2M
aidweather cache info

---

Data Licensing & Official NASA Attribution

NASA POWER data are open access and free of charge. In accordance with the NASA Earthdata Data Use and Attribution Policy, scientific publications, reports, and applications utilizing aidweather must properly cite the NASA POWER Project and acknowledge the primary satellite/reanalysis source products.

Suggested Acknowledgment Text:

"Meteorological and solar energy parameters were retrieved from the NASA Prediction Of Worldwide Energy Resources (POWER) project using aidweather v0.1.4. NASA POWER meteorological products originate from the GMAO MERRA-2 / GEOS-IT assimilation models, and solar radiation products originate from NASA LaRC CERES / FLASHFlux / SRB satellite observations."

---

License

Apache-2.0. See LICENSE.