usdata
Unified Python SDK and CLI for discovering, fetching, and tracking the provenance of U.S. public scientific data (NOAA, USGS, NASA, and more).
Status: pre-alpha.
noaa:ghcn-dailyandnoaa:nexrad-level2fetch real data with provenance; other registry entries are stubs. See docs/roadmap.md.
Install
pip install usdata # or: uv add usdata
Usage
from usdata import build_query, get, search
from usdata.fetch import fetch
for r in search("precipitation", location="Oklahoma"):
print(r.dataset.id, r.dataset.title)
ds = get("noaa:ghcn-daily")
query = build_query(
lat=35.39,
lon=-97.60,
radius_km=15,
start="2024-05-06",
end="2024-05-07",
variables=["PRCP", "TMAX"],
)
for item in fetch(ds, query):
print(item.path, item.provenance.checksum)
usdata search "tornado radar" --state OK
usdata info noaa:ghcn-daily
usdata fetch noaa:ghcn-daily --lat 35.39 --lon -97.60 --radius-km 15 \
--start 2024-05-06 --end 2024-05-07 --vars PRCP,TMAX
usdata fetch noaa:ghcn-daily -p stations=USW00013967 --start 2024-01-01 --end 2024-12-31
usdata fetch noaa:nexrad-level2 --lat 35.47 --lon -97.52 \
--start 2024-05-06T20:00 --end 2024-05-06T23:00 # nearest radar (KTLX)
usdata fetch noaa:nexrad-level2 -p site=KTLX --start 2024-05-06T20:00 --end 2024-05-06T20:30 --dry-run
usdata pull dataset.yaml
Fetched files land in ~/.cache/usdata/<provider>/<dataset>/ (override with
USDATA_CACHE_DIR or --cache-dir), each with a .provenance.json sidecar
recording source URL, retrieval time, checksum, size, and license.
A manifest declares every input a project needs; pull fetches them and writes
a lockfile with checksums and provenance so the inputs can be reproduced:
name: tornado-environment
sources:
- dataset: noaa:nexrad-level2
location: oklahoma
start: 2024-05-06
end: 2024-05-07
- dataset: noaa:ghcn-daily
location: oklahoma
start: 2024-05-01
end: 2024-05-31
Development
git clone https://github.com/jakeryderv/usdata && cd usdata
just setup # install toolchain and dependencies
just test # unit tests
just check # format, lint, typecheck, tests (what CI runs)
just run search radar
Integration tests that hit live services run with just test-integration.
Releases are published to PyPI by tagging: create a GitHub release and the
publish.yml workflow uploads via trusted publishing.
See docs/architecture.md for how the pieces fit and docs/adr/ for why.
License
Apache-2.0
1 maintainer
Release files for usdata 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| usdata-0.2.0.tar.gz | 22.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| usdata-0.2.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 53.6 kB
Release files / usdata-0.2.0.tar.gz
| Download URL | usdata-0.2.0.tar.gz |
|---|---|
| Size | 22.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
91ccfa0a14dcbe43ee0714d5cc25ef0700e21d136599b95297f13489837bcab2
|
|
BLAKE2b-256 checksum How to use checksums |
50c86425ed0215c4b1ba32e91d04300d2e45a2adaec4f4279479202012db5d9f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / usdata-0.2.0-py3-none-any.whl
| Download URL | usdata-0.2.0-py3-none-any.whl |
|---|---|
| Size | 30.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c3884a30a31f52379ae1461018952fc1af274864e57fbb1d726379e2c5c5829b
|
|
BLAKE2b-256 checksum How to use checksums |
8bfb18481da28662b7248f205606308923a24c87096933528e370d73aebb4f33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
