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: just release minor opens a version-bump PR; merging it publishes
to PyPI and creates the tag and GitHub release. See
docs/versioning.md.
See docs/architecture.md for how the pieces fit, docs/adr/ for why, and CONTRIBUTING.md to add a dataset.
License
Apache-2.0
1 maintainer
Release files for usdata 0.2.1
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.1.tar.gz | 24.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| usdata-0.2.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 56.8 kB
Release files / usdata-0.2.1.tar.gz
| Download URL | usdata-0.2.1.tar.gz |
|---|---|
| Size | 24.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
46c55f533eb65a236f58f3b34fb3d47967644ace5f9cdf5313ce18d2e044a99b
|
|
BLAKE2b-256 checksum How to use checksums |
091f2a81bb3d62c49e5f26be27ca0bdda0493dd8abd74d10db65a0f8c20a2a02
|
| 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.1-py3-none-any.whl
| Download URL | usdata-0.2.1-py3-none-any.whl |
|---|---|
| Size | 32.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5be20f547be7f4fa25baf262aeaa1d6666fa024c4b3af473e81e6d22355c8c3e
|
|
BLAKE2b-256 checksum How to use checksums |
6865e26e79e7d44115307008165b6a3ff3998263c766914337981d3fdcfbfc0c
|
| 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}
|
